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Import-Module -Name .\Module.psd1 
[ModuleClass]: :new() 


Property 


PowerShell must be restarted to show the change in behavior when running the same command inside a function: 


function Import-Something { 
Import-Module -Name .\Module.psd1 -Scope Global 


} 


Running Import-Something will, as the command says, import the module in the global scope. However, ScriptsToProcess 
still executes in the caller scope, that is, the scope of the function. Therefore, the class, exposed only via ScriptsToProcess , is 
still not available in the global scope, as the following shows: 


Import-Something 
Get-Module Module 
ModuleType Version PreRelease Name ExportedCommands 


Script Module Get-Something 
[ModuleClass]: :new() 
InvalidOperation: Unable to find type [ModuleClass]. 


ScriptsToProcess can be useful in the right circumstances, but it is not a fix for every problem with module content. 


Remove-Module will attempt to remove module content from the session. If explicit actions are required when a module is 
removed, the OnRemove event can be used. 


The OnRemove event 


The OnRemove event is raised when you use Remove-Module . Any script block assigned to the event as a handler will be 
invoked. The event handler may be used to trigger a cleanup of the artifacts created by the module (if required). 


The ModuleInfo object provides access to the OnRemove event handler via the $executionContext variable when it is used in 
the psm1 file 


gexecutionContext.SessionState.Module.OnRemove 


The following module creates a filenamed log.txt when the module is imported. An OnRemove handler is added to the 
module to attempt to release a lock created by the StreamWriter on the file when the module is removed: 


@' 
using namespace System. IO 
$path = Join-Path $PSScriptRoot -ChildPath 'OnRemove.log' 
$stream = [StreamWriter][File]::OpenWrite($path) 
$stream.WriteLine('Initialising module’ ) 
gexecutionContext .SessionState.Module.OnRemove = { 

$stream.WriteLine('Closing log') 

$stream.Flush() 

$stream.Close() 


} 
'@ | Set-Content OnRemove.psm1 


The file is created when the module is imported, anda Streamwriter is created: 


Import-Module -Name .\OnRemove.psm1 
Get-ChildItem -Path OnRemove. log 
Directory: C:\Workspace 


Mode LastWriteTime Length Name 


-a--- 17/04/2021 10:19 © OnRemove. log 


Commands such as Get-Content cannot read the file; it is locked by the StreamWriter . 


Get-Content .\OnRemove.log 
Get-Content: The process cannot access the file 'C:\Workspace\OnRemove.log' because it is being used 
by another process. 


Running Remove-Module triggers the OnRemove event. The OnRemove event writes one final line, flushes the buffer 
( StreamWriter does not immediately write to the file), and closes the stream. 


Once the stream is closed, Get-Content is able to read the file content: 


Get-Content -Path OnRemove. log 


Initialising module 
Closing log 


This event only runs when Remove-Module is used; it does not trigger if the PowerShell console is closed. In this case, the only 
difference is that the Closing log line is not written. 


Summary 


Modules are an important part of PowerShell as they encapsulate related functions (and other content). You can publish 
modules to public repositories such as the PowerShell Gallery, or any internal PowerShell repositories that may be in use. 


Module layout in PowerShell is flexible beyond the creation of a psm1 file (ora d11 file in the case of a binary module). 


You can optionally include a psd1 file to describe information about the module, including versions, what should be made 
available to anyone importing the module, and other metadata such as project information. 


Multi-file module layouts are common as they allow authors to manage content in separate files rather than a single monolithic 
root module. Some module authors choose to merge content into a single file as part of a publishing process, while others are 
happy to load individual files via the root module. 


You can use module scope to store the information a module needs to work; for example, authentication tokens used with a 
remote service. 


You can use PowerShell classes within a module and return instances of classes via functions to users of a module. Directly using 
classes within a module requires the use of the using module statement. 


You can perform actions before importing a module via the ScriptsToProcess property in a module manifest and when 
removing a module using Remove-Module via the OnRemove event. 


In the next chapter, Chapter 21, Testing, you'll explore static analysis and unit testing in PowerShell. 
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21 
Testing 


The goal of testing in PowerShell is to ensure that the code works as intended. Automatic testing ensures that this continues to be 
the case as code is changed over time. 


Testing often begins before code is ready to execute. PSScriptAnalyzer can look at code and provide advice on possible best 
practices that help prevent common mistakes. PSScriptAnalyzer uses what is known as static analysis. 


Unit testing, the testing of the smallest units of code, starts when the code is ready to execute. Tests can be created before the 
code when following practices such as Test-Driven Development (TDD). A unit test focuses on the smallest parts of a module, 
the functions and classes. A unit test strives to validate the inner workings of a unit of code, ensuring that conditions evaluate 
correctly, that it terminates or returns where it should, and so on. 


Testing might extend into systems and acceptance testing, although this often requires a test environment to act against. 
Acceptance testing may include black-box testing, used to verify that a command accepts known parameters and generates an 
expected set of results. Black-box testing, as the name suggests, does not concern itself with understanding how a block of code 
arrives at a result. 


This chapter covers the following topics: 


e Static analysis 


e Testing with Pester 


Before beginning with the main topics of the chapter, there are some technical requirements to consider. 


Technical requirements 


The following modules are used in this chapter: 


e PSScriptAnalyzer 1.19.1 
e Pester 5.1.1 
e ShowPSAst 1.0 


Static analysis 


Static analysis is the process of evaluating code without executing it. PSScriptAnalyzer uses static analysis. 


In PowerShell, static analysis most often makes use of an Abstract Syntax Tree (AST): a tree-like representation of a piece of 
code. In PowerShell, an element of a script is represented by a node in the syntax tree. AST was introduced with PowerShell 3. 


The largest elements represent the script itself, the root of the tree in effect. Each element added to the script is represented by a 
child node. For example, the parameter block is described by a ParamBlockAst object, an individual parameter by a 
ParameterAst , and so on. 


Evaluating elements of the AST is the basis for many of the rules implemented in PSScriptAnalyzer . 


PSScriptAnalyzer 


The PSScriptAnalyzer module is used to run a series of rules against a file or string containing a script. You can install the tool 
can using the following code: 
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Install-Module PSScriptAnalyzer 


You can use PSScriptAnalyzer to inspect a script with the Invoke-ScriptAnalzyer command. For example, the tool will 
raise one error and one warning for the following script: 


@' 
[CmdletBinding() ] 
param ( 

[Parameter (Mandatory) ] 

[String ]$Password 
) 
$credential = [PSCredential]: :new( 

r \USER® 5 

($Password | ConvertTo-SecureString -AsPlainText -Force) 
) 


$credential.GetNetworkCredential() .Password 
'@ | Set-Content Show-Password.ps1 


When Invoke-ScriptAnalyzer is run on the file, two rule violations are shown, one for the use of ConvertTo-SecureString , 
and one for the $Password parameter using plain text: 


Invoke-ScriptAnalyzer .\Show-Password.ps1 | Format-List 
RuleName : PSAvoidUsingConvertToSecureStringwWithPlainText 
Severity : Error 
Line 2 © 
Column : 18 
Message : File 'Show-Password.psi1' uses ConvertTo-SecureString 
with plaintext. This will expose secure information. 
Encrypted standard strings should be used instead. 

RuleName : PSAvoidUsingPlainTextForPassword 

Severity : Warning 

Line 3 3 

Column : 5 

Message : Parameter '$Password' should use SecureString, 
otherwise this will expose sensitive information. See 
ConvertTo-SecureString for more information. 


This is one of many best-practice style rules that you can use to test a script. 


Configurable rules 


PSScriptAnalyzer includes 64 default rules. Most of these rules are automatically evaluated when a script is analyzed. Several 
rules require configuration before they can be used; these are not enabled by default. 


The following command shows the rules that must be explicitly configured before they can be applied: 


Get-ScriptAnalyzerRule | Where-Object { 
$_.ImplementingType.BaseType.Name -eq 'ConfigurableRule' 


Conversely, the rules that are evaluated by default (without extra configuration) are shown with the following command: 


Get-ScriptAnalyzerRule | Where-Object { 
$_.ImplementingType.BaseType.Name -ne 'ConfigurableRule' 


Configurable rules may be configured using either a settings file or a Hashtable that describes the configuration for a rule. The 
following example shows how to use the PSUseCorrectCasing rule against a script read from a string: 
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$params = @{ 
ScriptDefinition = 'get-process' 
Settings = @f{ 
Rules = @f{ 


PSUseCorrectCasing = @{ 
Enable = $true 


} 


} 
} 


Invoke-ScriptAnalyzer @params 


Once the configuration for the rule is added, the rule will execute according to the settings for that rule. The settings for the rule 
are documented in the PSScriptAnalyzer repository. The document for PSUseCorrectCasing is: 
https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCorrectCasing.md 


Note that the rule documentation omits the PS prefix on the rule name. Several other rules, such as PlaceOpenBrace require 
configuration in a similar manner. 


PSScriptAnalyzer includes several built-in settings files, which will tab complete when using the Settings parameter. For 
example: 


Invoke-ScriptAnalyzer .\Show-Password.ps1 -Settings CodeFormatting 


The settings used by each are not documented in Help for the module, but the content of each file can be viewed in the module 
directory. You can either use these files or as an example to build a customized settings file. 


You can view the settings files shipped with PSScriptAnalyzer on GitHub: 
https://github.com/PowerShell/PSScriptAnalyzer/tree/master/Engine/Settings. 


It is sometimes hard to meet the requirements of all rules in PSScriptAnalyzer . Rules can be suppressed globally in the 
settings file, or rules can be suppressed in code. 


Suppressing rules 
It is rarely realistic to expect any significant piece of code to pass all the tests that PSScriptAnalyzer will throw at it. 


Individual tests can be suppressed at the function, script, or class level. The following demonstrative function creates a 
PSCustomObject : 


@' 
function New-Message { 
[CmdletBinding() ] 
param ( 
$Message 
) 
[PSCustomObject J@{ 
Name = 1 
Value = $Message 
} 


} 
'@ | Set-Content New-Message.ps1 


Running PSScriptAnalyzer against a file containing the function will show the following warning: 


Invoke-ScriptAnalyzer -Path .\New-Message.ps1 | Format-List 
RuleName : PSUseShouldProcessForStateChangingFunctions 
Severity : Warning 
Line Hil 


Column : 10 

Message : Function 'New-Message'’ has verb that could change 
system state. Therefore, the function has to support 
"ShouldProcess'. 


Given that this function creates a new object in the memory, and does not change the system state, the message might be 
suppressed. This is achieved by adding a SuppressMessage attribute beforea param block: 


n New-Message { 


stics.CodeAna s.Suppre 


"PSUseShouldProcessForStateChangingFunctions', 


age ( 


d 


)] 
[CmdletBinding()] 


O 


PSScriptAnalyzer leverages an existing class from .NET to express suppressed rules. Visual Studio Code will offer to create an 
attribute when you start to type "suppress." The second argument, set to an empty string in the preceding example, is required 
but will be empty in most cases. 


Once added, Invoke-ScriptAnalyzer will cease to warn of the rule failure for this function only. 


AST is the basis for the majority of the rules used by PSScriptAnalyzer . 


Using AST 


The AST in PowerShell is available for any script block; an example is as follows: 


{ Write-Host 'content' }.Ast 
Attributes e 
UsingStatements S eh, 
ParamBlock ; 

BeginBlock 


ProcessBlock 

EndBlock : Write-Host 'content' 
DynamicParamBlock 

ScriptRequirements : 

Extent : { Write-Host ‘content’ } 
Parent : { Write-Host ‘content’ } 


The object returned describes each of the elements of the script (or script block in this case). It shows that the command in the 
script block is in the end block, the default block. 


The script block that defines a function can be retrieved via Get-Command : 


function Write-Content { 'content' } 
( ).ScriptBlock 
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Or the script block defining a function can be retrieved using Get-Item : 


fur 1 Write-Content { 'content' } 
( function: \ ).ScriptBlock 


The preceding approaches have one thing in common, PowerShell is immediately parsing the script and will stop if there are 
any parser errors. The impact of this can be seen if an error is inserted into a script block; the syntax tree will not be accessible: 


{ 
Write-Host 


--String-- 


} 


ParserError: 
Line | 
3 | --String-- 
| a 


| Missing expression after unary operator ' 


To allow access to the AST, regardless of errors in the script, you can use the Parser class to read content either from a file or 
from a string. 


The Parser class is accessed under the System.Management .Automation.Language namespace. The following example uses 
the ParseInput method to read PowerShell content from a string: 


amespace System.Management .Automation. Language 
$script = @' 
Write-Host 
--String-- 


[Parser]::ParseInput($script, [ref]$null, [ref]$nu11) 


The ParseFile method can be used in place of ParseInput . The same arguments are used but the string containing the script 
can be replaced for a path to a file (a full path, not a relative path). 


Two of the method arguments to the ParseInput method in the previous example are set as references to $null . This 
essentially means they are ignored at this point. Ordinarily, the first would be used to fill an existing array of tokens, the second 
an array of errors. Tokens are explored in more detail later in this section. 


The errors array reference can be used to capture parse-time errors, such as the error shown when attempting to create the script 
block. 


pace System.Management .Automation.Language 


ns = @() 


$script = @' 
Write-Host 
--String-- 


Parser]::ParseInput($script, [ref]$tokens, [ref]$ 


rors) 


You can view the content of the array after the ParseInput method has completed: 


$errors | Format-List 

Extent : 

ErrorId : MissingExpressionAfterOperator 

Message : Missing expression after unary operator '--'. 


IncompleteInput : False 

Extent : String-- 

ErrorId : UnexpectedToken 

Message : Unexpected token 'String-- 
IncompleteInput : False 


in expression or statement. 
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The original script block only showed one error, but parsing stopped at the first error. This approach shows all syntax errors. If 
attempting to fix such errors, a top-down approach is required; one syntax error can easily cause another. 


Returning to the AST object, the object represents a tree, therefore it is possible to work down through the list of properties 
getting to more specific elements of the script. Each element has a different type. The following example includes 

ScriptBlockAst , StatementAst , NamedBlockAst , PipelineAst , and CommandAst (and more as the more detailed 
elements of the script are explored). 


The following example gets the CommandAst for the Get-Process command. That is the part of the script that represents just 
the Get-Process -ID $PID: 


$ast = { Get-Process -ID $PID | Select-Object Name, Path }.Ast 
gast.EndBlock.Statements[@].PipelineElements[@] 


All named blocks, such as the EndBlock here, can contain zero or more statements. Each statement can contain one or more 
pipeline elements. The Select-Object command in this example is in index 1 of the PipelineElements property. 


You can use a module called ShowPSAst to visualize the tree; the module uses Windows Forms to draw a GUI and is therefore 
only compatible with Windows systems. 


Visualizing the AST 


The ShowPSAst module, available in the PowerShell Gallery, may be used to visualize the AST tree. Install the module with: 
Install-Module ShowPSAst -Scope CurrentUser 


Once it's installed, you can use the Show-Ast command on a string, a function, a module, a script block, and so on. Running 
the following command will show the AST tree in an Ast Explorer window. 


Show-Ast 'Get-Process -ID $PID | Select-Object Name, Path' 


Figure 21.1 shows the explorer window: 


sE Ast Explorer - Oo x 


@ ScriptBlockAst [0,47) 
5- NamedBlockAst [0,47) 
&PipelineAst [0,47) 
© CommandAst [0,20) 
StringConstantExpressionAst [0,11) 
CommandParameterAst [12,15) 
VariableExpressionAst [16,20) 
&-CommandAst [23,47) 
StringConstantExpressionAst [23,36) 
S-ArrayLiteralAst [37,47) 
StringConstantExpressionAst [37,41) 
StringConstantExpressionAst [43,47) 


Get-Process -ID $PID | Select-Object Name, Path 


[PROPPED value typo 


Attributes System.Collections.Obje... AttributeAst[] 
UsingStatements _—_System.Collections.Obje... UsingStatementAst[] 
ParamBlock ParamBlockAst 
BeginBlock NamedBlockAst 
ProcessBlock NamedBlockAst 
EndBlock |Get-Process -ID $PID | ...|NamedBlockAst 


DynamicParamBlock NamedBlockAst 


ScriptRequirements ScriptRequirements 
Extent (1,1)-(1,48) IScriptExtent 
Parent Ast 


Figure 21.1: The Ast Explorer window 


This tiny script with just one short line of code has 12 separate AST nodes in the tree. Attempting to access individual elements of 
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a script by expanding each property and array index quickly becomes impractical in large scripts. 


It is possible to search the AST tree using Find and FindAll methods on any AST node. 


Searching the AST 


Searches against the AST can use the Find , which finds the first match only, and FindAll methods of any AST node. The 
methods find descendant nodes of the current node. Therefore, a search ona PipelineAst instance will only find results 
beneath that node. 


An earlier example found the CommandAst for Get-Process by expanding properties in the AST: 


$ast = { Get-Process -ID $PID | Select-Object Name, Path }.Ast 
g$ast.EndBlock.Statements[@].PipelineElements[@] 


This can be rewritten to use the Find method instead. The key to the Find method is a predicate. The predicate is a script 
block that returns true or false. Each node is tested against the predicate and returned if the result is true. 


The simplest predicate is therefore as follows: 
$predicate = { $true } 


When used with the Find method, the first matching node is returned. This will be the ScriptBlockAst , the top-most node in 
the tree. The second argument states whether the Find (or FindA11 ) method should search nested script blocks. More on this 
shortly: 


using namespace System.Management .Automation. Language 
$ast = { Get-Process -ID $PID | Select-Object Name, Path }.Ast 
$predicate = { $true } 


Find willshow the ScriptBlockAst object and is therefore equal to the content of the $ast variable: 


UsingStatements 
ParamBlock 
BeginBlock 
ProcessBlock 


EndBlock : Get-Process -ID $PID | Select-Object Name, Path 

DynamicParamBlock 

ScriptRequirements : 

Extent : { Get-Process -ID $PID | Select-Object Name, 
Path } 

Parent : { Get-Process -ID $PID | Select-Object Name, 
Path } 


Finding the node for the Get-Process command requires a more complex predicate. Each node in the AST is passed as an 
argument into the predicate. This can either be accessed using $args[@] or by defining a parameter to accept that value (as the 
following code shows). The AST type required is CommandAst . CommandAst hasa GetCommandName method, which can be 
used to separate the command name from the arguments. Here is the updated predicate: 


using namespace System.Management .Automation. Language 
$ast = { Get-Process -ID $PID | Select-Object Name, Path }.Ast 
$predicate = { 

param ( $node ) 

$node -is [CommandAst] -and 

$node.GetCommandName() -eq 'Get-Process' 


This time the result of the search is the node describing Get-Process : 


gast.Find($predicate, $true) 
CommandE lements : {Get-Process, ID, $PID} 
InvocationOperator : Unknown 


DefiningKeyword 

Redirections : {} 

Extent : Get-Process -ID $PID 

Parent : Get-Process -ID $PID | Select-Object Name, Path 


As shown in the preceding example, each AST node returns an Extent property. The Extent property describes information 
about the position of a node within the larger script, such as where it begins and ends. 


$ast.Find($predicate, $true).Extent 
File : 
StartScriptPosition : System.Management .Automation.Language. Int... 
EndScriptPosition : System.Management.Automation.Language.Int... 
StartLineNumber 

StartColumnNumber 

EndLineNumber 

EndColumnNumber 

Text : Get-Process -ID $PID 

StartOffset : 9 

EndOffset : 29 


Line and column numbers may vary depending on the source script. 


This information can potentially be used to selectively edit a script if required. This technique is used by several commands in the 
PSKoans module (https: //github.com/vexx32/PSKoans) to replace or update content in existing scripts. 


As mentioned at the start of this section, searches like this are the basis for many of the rules in PSScriptAnalyzer . 
PSScriptAnalyzer supports a second type of rule, a rule based on tokens within a script. 


Tokenizer 


In addition to the AST, PowerShell can also convert a script into a series of tokens, each representing an element of a script with 
no hierarchy. 


One of the advantages of the tokenizer is that it will return tokens representing comments, whereas the AST ignores comments 
entirely: 


ce System.Management .Automation. Language 


ens = @() 


d ipt = @' 
# A short script 
Write-Host ‘Hello world' 


ser]::ParseInput($script, 


Once executed, the tokens that make up the script can be examined. The first two tokens are shown here: 


¢tokens | Select-Object -First 2 
Text : # A short script 
TokenFlags : ParseModeInvariant 
Kind > Comment 
HasError : False 
Extent : # A short script 


Text 

TokenFlags : ParseModeInvariant 
Kind : NewLine 

HasError : False 

Extent 
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Tokens are less useful than the AST when it comes to defining rules. The lack of context makes it more difficult to relate one 
token to another beyond the order in the array. Tokens might be used in a rule to validate the content of comments if necessary. 


The AST and tokens are used by PSScriptAnalyzer to implement rules. 


Custom script analyzer rules 


PSScriptAnalyzer allows custom rules to be defined and used. Custom rules might be used to test for personal or 
organization-specific conventions when striving for a consistent style; such conventions may not necessarily be widely adopted 
best practices, but instead locally established best practices. 


Script analyzer rules must be defined in a module psm1 file. The path to the module file may be passed in by using the 
CustomRulePath parameter or may be defined in a script analyzer configuration file. 


Creating a custom rule 


Ascript analyzer rule is a function within a module. The PSScriptAnalyzer module allows rules to be written to evaluate AST 
nodes or tokens. 


The name of the function is arbitrary. The community examples use the verb measure ; however, the use of this verb is not 
mandatory and does not affect discovery. The community example is linked here for reference: 


https ://github.com/PowerShell/PSScriptAnalyzer/blob/master/ScriptRuleDocumentation.md. 
The following examples use a much more lightweight format. This does not sacrifice functionality. 


The script analyzer engine examines each function in the custom rule module, looking for parameters with a particular naming 
style. If a parameter is found, the function is deemed to be a rule. 


If a rule is expected to act based on an AST node, the first parameter name must end with ast . The parameter must use one of 
the AST types, such as System.Management .Automation.Language.ScriptBlockAst . 


If a rule is expected to act based on a token, the first parameter name must end with token and must accept an array of tokens. 


AST-based rules 
Script analyzer rules are often simple; it is not always necessary for a rule to perform complex AST searches. 


The following example evaluates the named blocks dynamicparam, begin, process , and end. If one of the blocks is 
declared in a function, script, or script block, and it is empty, the rule will respond. 


The rule only accepts NamedBlockAst nodes, the smallest scope for the rule to effectively evaluate the script. The script analyzer 
only passes nodes of that type to the rule, and therefore, the rule itself does not have to worry about handling other node types 
or performing searches itself. 


The rule simply looks to see if the number of statements in the block is 0. If it is 0, then the rule triggers. 


The following rule is expected to be placed ina psm1 file. For the sake of this example, that file can be named 
CustomRules.psm1 : 
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using namespace Microsoft.Windows .PowerShell.ScriptAnalyzer.Generic 
using namespace System.Management .Automation. Language 
function PSAvoidEmptyNamedBlocks { 


[CmdletBinding() ] 
param ( 
[NamedBlockAst ]$ast 
) 
if (gast.Statements.Count -eq ©) { 
[DiagnosticRecord ]@f{ 
Message = ‘Empty {@} block.’ -f $ast.BlockKind 
Extent = $ast.Extent 
RuleName = $myinvocation.MyCommand.Name 
Severity = ‘Warning’ 
} 
} 


The rule returns DiagnosticRecord when it is triggered. The record is returned by the script analyzer provided the rule is not 
suppressed. The next command shows the rule in action: 


@' 
[CmdletBinding() ] 
param ( ) 
begin { } 
process { } 
end { 
Write-Host ‘Hello world' 
} 
'@ | Set-Content script.ps1 
$params = @{ 
Path = 'script.ps1' 
CustomRulePath = '.\CustomRules .psm1' 


} 


Invoke-ScriptAnalyzer @params 
The output from the command flags the begin and process blocks as they are empty: 


Invoke-ScriptAnalyzer @params 
RuleName Severity ScriptName Line Message 


PSAvoidEmptyNamedBlocks Warning script.ps1 4 Empty Begin ... 
PSAvoidEmptyNamedBlocks Warning script.ps1 5 Empty Process... 


Token-based rules are written in a similar manner. 


Token-based rules 


Rules based on tokens evaluate an array of tokens. The following example looks for empty single-line comments in a block of 
code. Comments are not a part of the syntax tree, so using tokens is the only option. This new rule can be added to the 
CustomRules.psm1 file created in the previous section: 
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using namespace Microsoft.Windows .PowerShell.ScriptAnalyzer.Generic 
using namespace System.Management .Automation. Language 
function PSAvoidEmptyComments { 
[CmdletBinding() ] 
param ( 
[Token[ ]]$token 
) 
$ruleName = ¢$myinvocation.MyCommand.Name 
$token.Where{ 
$_.Kind -eq 'Comment' -and 
$_.Text.Trim() -eq '#' 


}.ForEach{ 
[DiagnosticRecord]@{ 
Message = 'Empty comment. ' 
Extent = $_.Extent 
RuleName = $ruleName 
Severity = ‘Information’ 
} 
} 


As the name suggests, the rule will trigger when it encounters an empty line comment. This is demonstrated by the following 
example: 


@' 
[CmdletBinding() ] 

param ( ) 

# 

# Comment 

Write-Host ‘Hello world' 

'@ | Set-Content script.ps1 


The output from Invoke-ScriptAnalyzer shows the line that failed: 


= @{ 
Path 
CustomRulePath .\CustomRule 


Invoke-ScriptAnalyzer @params 
RuleName Severity ScriptName Line Message 


PSAvoidEmptyComments Information script.ps1 4 Empty comment. 


More custom rules 
For more examples of custom rules, please see: 
https: ithub.com/indented-automation/Indented.ScriptAnalyzerRules 


PSScriptAnalyzer is a fantastic tool that can attempt to enforce a specific style or help fix common problems. 


Testing with Pester 


Pester is a framework for executing tests. It includes tools to define and execute test cases against anything that can be written in 
PowerShell. 


This chapter focuses on Pester 5, the latest major release. Pester 5 is not installed by default; Windows ships with Pester 3.4. This 
pre-installed version can be ignored: 
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Install-Module Pester -Force -SkipPublisherCheck 


The -SkipPublisherCheck parameter is required as Pester has changed maintainer since the version shipped with Windows 
was released. The certificate issued to the pre-installed version differs from the certificate issued to the current version. 


You can use Pester to write tests for code and systems and everything in between. Pester is implemented as what is known as a 
Domain-Specific Language. It has specific functions that are implemented to behave like language keywords. For example, 

function is a language-specific keyword. Pester tests are written using PowerShell, but for the most part, the language, the 
keywords, and so on, are defined by and specific to Pester. 


The following example creates a test that asserts PowerShell 7 or greater should be in use. If the test runs in Windows 
PowerShell, the test will fail, and the results of that failure will be displayed to someone running the test. Pester tests must be 
saved in a file in Pester 5 so the following snippet saves content to a file before running Invoke-Pester : 


@' 
Describe 'PS developer workstation' { 
It 'PowerShell 7 is installed' { 
$PSVersionTable.PSVersion | 
Should -BeGreaterOrEqual 7.0.0 
} 


} 
'@ | Set-Content workstation.tests.ps1 


Invoke-Pester -Path workstation.tests.ps1 


The outcome of running the test is displayed in the console, although the results of the test are summarized by default. Times to 
perform discovery and execute tests may vary: 


Invoke-Pester -Path workstation.tests.ps1 
Starting discovery in 1 files. 
Discovery finished in 5ms. 


[+] C:\workspace\workstation.tests.ps1 91ms (2ms|86ms) 
Tests completed in 93ms 
Tests Passed: 1, Failed: @, Skipped: @ NotRun: @ 


Setting the -Output parameter to Detailed will show the results of each of the tests performed in the script. This test script 
only has one test. The difference is relatively small: 


Invoke-Pester -Path workstation.tests.ps1 -Output Detailed 
Starting discovery in 1 files. 
Discovering in C:\workspace\workstation.tests.ps1. 
Found 1 tests. 9ms 
Discovery finished in 13ms. 


Running tests from 'C:\workspace\workstation.tests.ps1' 
Describing PS developer workstation 
[+]PowerShell 7 is installed 4ms (1ms|3ms) 
Tests completed in 104ms 
Tests Passed: 1, Failed: @, Skipped: @ NotRun: @ 


Tests must be saved to a file 


This section focuses on test file content and not on the process of saving that content to a file. Test content 
should be saved to a file and run in the same manner as the preceding examples. 


Note that the Invoke-Pester command specifically looks for .tests.ps1 in file names. 


The previous example uses three of the major keywords used in Pester: 


e Describe — Groups tests for a particular subject together 


e It -Defines a single test that should be executed 
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e Should — Asserts what the value or result of an expression should be 


The condition used with the Should keyword simply states that the major version number should be 7 or greater. 


Testing methodologies 


Testing is a complex topic; it encompasses a wide range of different methodologies and concepts. The majority of these are 
beyond the scope of this chapter. Further reading is available on sites such as Wikipedia: 
https://en.wikipedia.org/wiki/Software testing. 


Two methodologies are of interest in this chapter. They are: 


e Acceptance testing 
e Unit testing 


Acceptance testing is used to validate that the subject of the tests conforms to a pre-defined state. The test for the version of 
PowerShell at the start of this section might be part of an acceptance test for a developer workstation. 


Acceptance testing in relation to PowerShell development strives to test the outcome of actions performed by a command (or 
script) without having any knowledge of how that script works. Acceptance testing is, therefore, a form of black-box testing and 
requires a system that code can be run against. 


Unit testing aims to test the smallest units of code and is a form of white-box testing. The author of a unit test must be familiar 
with the inner workings of the subject of the tests. 


Unit testing is most relevant in PowerShell when testing that the components of a module behave as they are expected to 
behave; that the different paths through a function, based on if statements and loops, are used correctly. Unit testing does not 
require a live service to act on. External calls are mocked, a fake response is returned. Mocking is explored later in this chapter. 


The advantage of putting tests in code is that they can be run whenever the state of the subject changes. It is possible to continue 
to prove that the subject of a set of tests is working as expected. 


One of the most challenging aspects of any testing process is figuring out what should be tested. 


What to test 


When testing systems, or performing acceptance testing, the following are rough examples of things that might be tested: 


e Installed software packages 

e File system paths or environment variables 

e Application or service configuration 

e Responses from remote systems the subject is expected to interact with 


e Network access and network configuration. 
When testing a module, or performing unit testing, consider testing the following: 


e Parameters (and parameter binding) 
e Any complex conditions and branches (conditional statements and loops) in the code 
e Acceptance of different input or expected values, including complex parameter validation 


e Exit conditions, especially raised errors or exceptions 


When writing a unit test, resist the temptation to test other functions or commands called by the unit of code. A unit test is not 
responsible for making sure that every command that it calls works. 


How extensive tests should be is debatable. Enough to ensure the functionality of a given script or module is perhaps the only 
real definition. 


Code coverage is one of the measures that is often used. It is the percentage of code that is visited when executing a set of tests. 
Pester is capable of measuring code coverage. The details of this are shown later in this section. However, while this is an 
interesting indicator, it does not prove that code has been effectively tested. 
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Perhaps the most important keywords in Pester are Describe , It , and Should . They are the backbone of any set of tests. 


Describing tests 


Pester includes keywords that are used to enclose and group tests together. This section explores the keywords that are used to 
enclose tests. They are: 


e Describe 
e Context 


e It 


The Describe and Context keywords are both used to enclose or group together sets of tests. The tests themselves are defined 
within an It statement. 


All test documents will include the Describe keyword and one or more It statements. 


About the Describe and Context keywords 
Describe is the top-most keyword used in a test document. It most often describes the subject of the tests. 


Context is essentially the same as Describe . It has the same capabilities and will contain one or more It statements. 
Context is typically used under Describe to group together small sets of tests, typically where the tests have a similar 
purpose or require similar start conditions. 


A test document might have a broadly defined subject, and several more specifically defined components. For example, a set of 
tests might be developed to describe the expected state of a developer workstation. The tests are broken down into more detailed 
sub-sections: 


Describe 'PS developer workstation' { 
Context 'PowerShell' { 


} 
Context ‘Packages’ { 


} 


The use of Context will become clear as tests grow in complexity and unit tests against PowerShell code are introduced later in 
this chapter. 


Describe , or each Context , can include one or more It blocks, which describe the expected outcome. 


About the It keyword 


The It keyword is used to define a single test. The test title should describe the purpose and potentially the expected outcome 
of the test: 


Describe 'PS developer workstation' { 
Context 'PowerShell' { 
It ‘PowerShell 7 is installed’ { 
} 
} 
Context ‘Packages' { 
It ‘git is installed’ { 
} 


It 'Terraform is installed’ { 


} 


The It keyword will contain one or more assertions using the Should keyword. 
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Should and assertions 


The Should keyword is used to assert the state of the thing it is testing. 


Should has 25 different parameter sets, one for each of the assertions it supports. The different assertions are documented in the 
Pester wiki along with an example: https: //pester.dev/docs/assertions/assertions. 


The example used at the start of this section uses one of the possible assertions, the -BeGreaterOrEqual assertion. Assertions 
have unsurprising options for the most part. If testing a Boolean value, -BeTrue or -BeFalse are appropriate. 


Comparisons are achieved using -Be, -BeLessThan, -BeLessOrEqual, -BeGreaterThan, -BeGreaterOrEqual , and so on. 


The first of the tests, the test for the installation of PowerShell 7, can be changed to allow it to run in Windows PowerShell as 
well. The point is to prove the system is in the expected state, not that the current runtime is PowerShell 7. The second Context 
is temporarily removed to focus on this one assertion. 


Describe 'PS developer workstation' { 
Context ‘PowerShell’ { 
It ‘PowerShell 7 is installed’ { 
Get-Command pwsh -ErrorAction SilentlyContinue | 
ForEach-Object Version | 
Should -BeGreaterOrEqual '7.0.0' 


Testing for errors is perhaps one of the most complex assertions and benefits from more extensive exploration. You can use a 
Should -Throw assertion to test whether a specific error is raised (or not) when running a command. 


Testing for errors 


The -Throw assertion is used to test whether a block of code throws a terminating error such as one raised when ErrorAction 
is set to Stop or when the throw keyword is used. 


The assertion can be used for several of the tests above, but for the sake of variety, it is only used to test for the installation of 
Chocolatey, a package manager for Windows: 


Describe 'PS developer workstation’ { 
Context ‘PowerShell’ { 
It ‘PowerShell 7 is installed’ { 
Get-Command pwsh -ErrorAction SilentlyContinue | 
ForEach-Object Version | 
Should -BeGreaterOrEqual '7.0.0' 


} 
Context 'Packages' { 


It 'Chocolatey is installed' { 
{ Get-Command choco -ErrorAction Stop } | 
Should -Not -Throw 


Notice how the expression being tested is defined as a script block, and that the script block is piped to the Should keyword. 


The assertion used in the preceding example expects there to be no error. There is therefore no need to test anything else about 
the error. 


If an error is expected to be thrown, then further tests might be beneficial. For example, attempting to divide 1 by 0 will raise an 
error: 
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Describe Division { 
It ‘Throws an error when 1 is divided by @' { 
{ 1/@ } | Should -Throw 


} 


This type of test is not specific; it does not differentiate between the actual problem and any other error that might occur. 
Changing the assertion, as the following shows, will still correctly identify that an error is thrown, but the error is no longer 
consistent with the descriptive name for the It statement: 


Describe Division { 
It 'Throws an error when 1 is divided by @' { 
{ throw } | Should -Throw 


} 


If this is saved toa division.tests.ps1 file, it can be run to show that the test passes: 


Invoke-Pester -Path .\division.tests.ps1 
Starting discovery in 1 files. 
Discovery finished in 5ms. 


[+] C:\workspace\division.tests.ps1 10@ms (4ms|93ms) 
Tests completed in 102ms 
Tests Passed: 1, Failed: @, Skipped: @ NotRun: @ 


Adding the -ExpectedMessage parameter is one way to tackle this. Testing for a specific message will greatly improve the 
accuracy of the test: 


Describe Division { 
It 'Throws an error when 1 is divided by @' { 
{ 1/0 } | Should -Throw -ExpectedMessage ‘Attempted to divide by zero.' 


} 


For the preceding exception, testing the message is potentially as good as it gets. However, since error messages are often written 
in a user's language, testing the message is a weak test as it demands the tests are run in a specific culture. 


The -Throw assertion allows both the error type and the fully qualified error ID to be tested instead. These are far more robust if 
the expression raising the error reveals them. The following example tests the fully qualified error ID: 


Describe ErrorID { 
It ‘Raises an error with a fully-qualified error ID' { 
{ Write-Error error -ErrorID SomeErrorID -ErrorAction Stop } | 
Should -Throw -ErrorId SomeErrorID 


This type of testing is far more accurate, it may be possible to attribute the ErrorID toa single statement in the code being 
tested rather than testing for any error anywhere. 


It is frequently necessary to perform setup actions prior to executing tests. Pester includes several named blocks for this purpose. 


Iteration with Pester 


It is often desirable to repeat the same test or tests for a different subject. Pester offers two different styles of iteration: 


e The It keyword has the TestCases parameter 


e The Describe and Context keywords have the ForEach parameter 
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The TestCases parameter for an It statement allows a single test to be executed against a set of predefined cases. 


Using the TestCases parameter 


The packages context of the "PS developer workstation" acceptance tests are a good candidate for test cases. A few packages 
were listed in the example context. The following tests assert that each of these should have been installed using Chocolatey, a 
package manager for Windows that can be downloaded from https: //chocolatey.org. 


With Chocolatey, the installation of a package can be tested using the following command: 


choco list -e terraform -1l -r 


If the exact package name ( -e ) is installed locally ( -1 ) it will be included in the output from the command. The -r 
parameter is used to limit output to essential information only, in this case just the package name and version. 


The version of the installed package is not relevant as far as the following tests are concerned. The tests might be extended to 
ensure a specific version in a real-world implementation: 


Describe 'PS developer workstation’ { 
Context ‘Packages’ { 
It 'Chocolatey is installed’ { 
{ Get-Command choco -ErrorAction Stop } | 
Should -Not -Throw 


It '<Name> is installed' -TestCases @( 


@{ Name = 'terraform' } 
@{ Name = 'git' } 
) -Test { 


choco list -e $Name -1 -r | Should -Match $Name 
} 


Each test case is defined as a Hashtable, and all keys in the Hashtable are available as variables inside the It statement 
automatically. This contrasts with Pester 4, which required a param block inside It . 


The keys in the Hashtable can be used in the It description by enclosing the name in < >. 


Pester allows the expansion of properties of values in the description. For instance, using <Name.Length> in the description 
would show the length of the string in the Name key. Not a very practical use in this case. 


The outcome of running the tests can be viewed by saving the previous example to a file, such as workstation.tests.ps1 , and 
using Invoke-Pester : 


Invoke-Pester -Path .\workstation.tests.ps1 -Output Detailed 
Running tests from 'C:\workspace\workstation.tests.ps1' 
Describing PS developer workstation 

Context Packages 
[+] Chocolatey is installed 2@ms (15ms|5ms) 


[+] terraform is installed 802ms (799ms|3ms) 
[+] git is installed 786ms (786ms|1ms) 

Tests completed in 1.79s 

Tests Passed: 3, Failed: @, Skipped: @ NotRun: @ 


The preceding tests are executed against a single subject, the local machine. You can use the -ForEach parameter of Describe 
or Context to run a set of tests against more than one subject. 


Using the ForEach parameter 


The -ForEach parameter can be used to execute either a Describe or Context block against an array of values. Continuing 
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with the theme of acceptance testing, it might be desirable to run a set of tests against several different servers. 


The following tests assert that the DNS service exists on a set of Windows servers. The names of the servers are made up. The 
tests will potentially work if a meaningful set of names is provided: 


Describe "DNS servers" -ForEach @( 


"dnse@1' 
"dns@2' 
) -Fixture { 
It "The DNS service is running on $_" { 
$params = @f{ 
ClassName = 'Win32_Service' 
Filter = 'Name="dns"' 
ComputerName = $_ 
} 


Get-CimInstance @params | Should -Not -BeNullOrEmpty 


The $_ variable used in the preceding example is created by Pester and is used to access each of the values in the -ForEach 
array in turn. 


Get-CimInstance is used in the preceding example but Invoke-Command and Get-Service might be used instead if 
appropriate. You should implement tests in a way that is appropriate to the environment the test executes in. 


All the tests used in this section have the potential to fail and raise errors that are not handled within the test. In the cases of the 
tests using choco , the tests will raise an error if Chocolatey is not actually installed. In the case of the last example, the tests will 
raise an error if the server does not exist or Get-CimInstance fails for any other reason. 


Problems of this kind can potentially be handled by skipping tests or marking a test as inconclusive. 


Conditional testing 
There are two possible approaches for dealing with tests that cannot be executed: 


e The result of It can be forcefully set by using Set-ItResult 
e The test can be skipped entirely using the -Skip parameter 


Set-ItResult can be used with the <Name> is installed test, enabling the test to account for situations where the choco 
command is not available. 


Using Set-ItResult 


The Set-ItResult command can be used inside any It statement. In the following example, it is used to change the result of 
the It statement based on the availability of the choco command: 


Describe 'PS developer workstation' { 
Context 'Packages' { 
It '<Name> is installed' -TestCases @( 


@{ Name = 'terraform' } 
@{ Name = 'git' } 
) -Test { 


if (Get-Command choco -ErrorAction SilentlyContinue) { 
choco list -e $Name -1 -r | Should -Match $Name 

} else { 
Set-ItResult -Skipped 


} 
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The name of the test is changed in the result to show it has been skipped if the choco command is not available: 


PS> Invoke-Pester -Path .\workstation.tests.psi -Output Detailed 
Starting discovery in 1 files. 

Discovering in C:\workspace\workstation.tests.ps1. 

Found 2 tests. 27ms 

Discovery finished in 31ms. 

Running tests from 'C:\workspace\workstation.tests.ps1' 


Describing PS developer workstation 

Context Packages 
[!] terraform is installed is skipped 14ms (9ms|5ms) 
[!] git is installed is skipped 2ms (1ms|1ms) 

Tests completed in 217ms 

Tests Passed: ©, Failed: ©, Skipped: 2 NotRun: @ 


Set-ItResult allows the result to be set to Inconclusive , Pending , or Skipped . 


The advantage of using Set-ItResult , in this case, is that the test cases are still processed. The Name value is expanded in the 
output of the tests. The -Skip parameter will stop Pester from expanding this value. 


You can use the -Skip parameter on any It block that isnot using -TestCases . 


Using Skip 
You can use -Skip , a switch parameter, to bypass one or more tests. 


You can set an explicit value to the parameter such as a value based on a variable. The following example changes the test for 
the installation of Chocolatey. It will be skipped if the current operating system is not Windows: 


Describe 'PS d r < We 
Context ‘| cag { 
Et ach | J' -Skip:(-not $IsWindows) { 
{ Get-Command choco -ErrorAction Stop } | 
Should -Not -Throw 


The $IsWindows , $IsMacOS , and $IsLinux variables are all automatically available in PowerShell 6 and above. 


Values used with the -Skip parameter must be available during the Discovery phase in Pester. 


Pester phases 


Pester 5 introduces the concept of different phases when executing tests. This is visible in the output of the tests run in this 
section: 


Starting discovery in 1 files. 
Discovering in C:\workspace\workstation.tests.ps1. 
Found 2 tests. 27ms 


Discovery finished in 31ms. 
Running tests from 'C:\workspace\workstation.tests.ps1' 
Describing PS developer workstation 


First, the Discovery phase is run. During the Discovery phase, Pester attempts to find all the tests it will be running. Each test is 
defined by an It statement. 


The Run phase will execute only those tests found during the Discovery phase. 


This concept is new in Pester 5; it means that everything used to define what will be tested must be in place before discovery 
occurs, which affects the dynamic creation of tests. 
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Pester provides a BeforeDiscovery block, which may be placed either before or inside Describe . The code in 


BeforeDiscovery is, as the name suggests, executed before the Discovery run starts. 


The last example used the predefined $IsWindows variable. As this is built-in, it is automatically available during the Discovery 
phase. 


If the tests were instead to be executed based on a user-defined variable, this variable would need creating in BeforeDiscovery . 
The same limitation applies to any test cases used with the -TestCases parameter, and any arrays used with -ForEach 
parameters. 


An earlier example used -ForEach to attempt to execute tests on an array of server names. If the server names had to be read 
from an external system, then that discovery action would be placed in the BeforeDiscovery block. 


The following example uses the Get-ADComputer command from the ActiveDirectory module to get the list of servers to 
query. These tests will only succeed if the ActiveDirectory module is installed, and it is able to find server names to test: 


BeforeDiscovery { 

$dnsServers = Get-ADComputer -Filter 'name -like "dns*"' 
} 
Describe "DNS servers" -ForEach $dnsServers -Fixture { 

It "The DNS service is running on $($_.Name)" { 


$params = @{ 
ClassName = 'Win32_Service' 
Filter = 'Name="dns"' 


ComputerName = $ _.DnsHostName 


Ir 
Get-CimInstance @params | Should -Not -BeNullOrEmpty 


BeforeDiscovery is therefore useful to ensure that the values needed to define which tests are present are in place when Pester 
is attempting to discover which tests are going to be executed. 


Pester provides other named blocks to execute code at certain points during the Run phase. These can be used to define variables 
and set up conditions for tests. They should avoid defining which tests are executed. 


Before and After blocks 


Pester offers several blocks that you can use to perform actions before and after tests execute. Such blocks may be used to set up 
an environment or tear it down afterwards. 


The blocks are: 


e BeforeAll 
e BeforeEach 
e AfterAll 

e AfterEach 


The All blocks execute once, before (or after) any of the tests in that block. The Each blocks execute before (or after) 
individual It blocks. 


Each block can exist once in any Describe or Context block. Ifa Describe block contains BeforeAll , and a nested 
Context also contains BeforeAll then both blocks will be executed (the Describe instance first, then the Context 
instance). 


The BeforeAll and BeforeEach blocks are frequently used when defining a Mock for a command in unit testing. 


Mocking commands 


Mocking is used to reduce the scope of a set of tests and a vital part of unit testing. Mocking allows the implementation of a 
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command to be replaced with one defined in a test. Mocked commands are created using the Mock keyword. 


The Mock keyword may be used in BeforeAll , BeforeEach, or It. 


The following command reads a CSV file, then either starts or stops a service based on whether that service matches the state in 
the file. 


@' 
function Set-ServiceState { 
[CmdletBinding() ] 
param ( 
[string ]$Path 
) 
Import-Csv $Path | ForEach-Object { 
$service = Get-Service $ .Name 
if (¢$service.Status -ne $ .ExpectedStatus) { 
if ($_.ExpectedStatus -eq 'Stopped') { 
Stop-Service -Name $ .Name 
} else { 
Start-Service -Name $ .Name 
} 
} 
J 
if 


'@ | Set-Content -Path module.psm1 


Place this function in a file named module. psm1 ; it will be used as the subject of the first set of unit tests. 


To effectively test this command, the system running the tests would need to have all the services listed in the CSV file, and it 
would have to be possible to change the state of those services. 


Instead, depending on a complete system to execute on, the results of the code can be tested by mocking each of the commands 
external to the function. 


Two of the commands ( Import-Csv and Get-Service) must return information, and two ( Start-Service and Stop- 
Service ) return nothing at all. 


Using Mock for Start-Service and Stop-Service is therefore straightforward: 


Mock Start-Service 
Mock Stop-Service 


The output from Import-Csv and Get-Service needs to resemble the output from those real commands. The output can be 
simplified depending on what the command is expecting to do with that. 


Import-Csv is expected to output an object witha Name and ExpectedStatus property: 


Mock Import-Csv { 
[PSCustomObject J@f{ 
Name = 'servicel' 
ExpectedStatus = ‘Running’ 


Get-Service is expected to return an object with a Status property, but no other properties from Get-Service are used. 
Mocking Get-Service allows the tests to run even if the current computer does not have the service being tested: 


504 


Mock Get-Service { 
[PSCustomObject J@f{ 
Status = 'Stopped' 


The name of the service is a parameter value for Get-Service and it is not used by the function. The name of the service can 
therefore be ignored in the object the mock emits. 


Given the outputs that have been defined above, the expectation is that when running Set-ServiceStatus , you will use the 
Start-Service command to start servicel . 


Execution of the mock can be tested by using a Should -Invoke assertion: 


@' 
BeforeDiscovery { 

Import-Module .\module.psm1 -Force 
} 
Describe Set-ServiceState { 

BeforeAll { 

Mock Get-Service -MockWith { 
[PSCustomObject ]J@{ 
Status = 'Stopped' 


} 
be 
Mock Import-Csv -MockWith { 
[PSCustomObject ]J@{ 
Name = 'servicel' 
ExpectedStatus = ‘Running’ 
} 
} 


Mock Start-Service 
Mock Stop-Service 


} 


It 'When ExpectedStatus is running, starts the service’ { 
Set-ServiceState -Path file.csv 
Should -Invoke Start-Service 


} 


ir 
'@ | Set-Content Set-ServiceState.tests.ps1 


The previous command saves the tests ina Set-ServiceState.tests.ps1 file. The content of this file is modified during this 
section; the size of the file prohibits repeating the content in full for each change. 


As Import-Csv is being mocked in the tests, the name used for the file (the Path parameter) is not relevant and you can use a 
made-up value. 


The result of running the tests is shown here: 


Invoke-Pester -Path .\Set-ServiceState.tests.ps1 
Starting discovery in 1 files. 
Discovery finished in 10ms. 


[+] C:\workspace\Set-ServiceState.tests.ps1 127ms (16ms|102ms) 
Tests completed in 13@ms 
Tests Passed: 1, Failed: @, Skipped: @ NotRun: @ 


In this function, there are three possible paths through the code for each service: 


1. The service is in the expected state and neither Start-Service or Stop-Service run. 
2. The service is stopped but was expected to be running, and Start-Service should run. 


3. The service is running but was expected to be stopped, and Stop-Service should run. 
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A parameter filter for the Get-Service mock can be created to allow a different output based on the service name, which will 


allow each of the paths to be tested. 


Parameter filtering 


You can apply parameter filters to define when that mock should be used. Parameter filters are added using the - 
ParameterFilter parameter for Mock . The parameter filter is a script block that is most often used to test a parameter value 
used when calling the mock. 


First, the mock for Import-Csv can be extended by adding two more services: 


Mock Import-Csv -MockWith { 


[PSCustomObject J@f{ 
Name = 'servicel' 
ExpectedStatus = ‘Running’ 
} 
[PSCustomObject J@f{ 
Name = 'service2' 
ExpectedStatus = ‘Running’ 
} 
[PSCustomObject J@f{ 
Name = 'service3' 
ExpectedStatus = 'Stopped' 
} 


Then the original mock for Get-Service is replaced with three new mocks. Each usesa -ParameterFilter and tests a 
different service name: 


Mock Get-Service -ParameterFilter { 
$Name -eq ‘servicel' 
} -MockWith { 
[PSCustomObject J@f{ 
Status = ‘Running’ 


} 


Mock Get-Service -ParameterFilter { 
$Name -eq ‘service2' 
} -MockWith { 
[PSCustomObject J@f{ 
Status = 'Stopped' 


} 


Mock Get-Service -ParameterFilter { 
$Name -eq ‘service3' 
} -MockWith { 
[PSCustomObject J@f{ 
Status = ‘Running’ 


Finally, the It block is adjusted. For this version, Start-Service will run once, and Stop-Service will run once. The 
previous assertion simply stated that Start-Service would run, which implicitly means it runs one or more times: 


It ‘Ensures all services are in the desired state’ { 
Set-ServiceState -Path file.csv 
Should -Invoke Start-Service -Times 1 
Should -Invoke Start-Service -Times 1 


Once the changes are made to the tests file, the single test will pass. However, while this test passes, it remains difficult to 
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explicitly relate cause to effect. A failure in any one or more of the comparisons will cause the preceding tests to fail, but it will 


not indicate which value caused the failure. 


Instead of using -ParameterFilter , a more robust approach, in this case, might be to use Context to change the values 
provided by Import-Csv or the values returned by Get-Service . 


Overriding mocks 


You can use Mock ineitheran It ora Context block to override an existing mock or create new mocks which are specific to 
a specific branch of code. Mock is scoped to the block it is created in, therefore a Mock createdin It only applies to that single 
It block. 


Generally, the safest approach is to define default mocks under a BeforeAll in Describe , then to override those as needed. 
The presence of the default mocks acts as a safeguard. Running the subject of the tests, Set-ServiceState , in the following 
example, will only ever call a mocked command. It will never accidentally call the real command because something has been 
missed from a specific context: 


@' 
BeforeDiscovery { 
Import-Module .\module.psm1 -Force 
} 
Describe Set-ServiceState { 
BeforeAll { 
Mock Get-Service -MockWith { 


[PSCustomObject ]@{ 
Status = ‘Running’ 
J 
} 
Mock Import-Csv -MockWith { 
[PSCustomObject ]J@{ 
Name = 'servicel' 
ExpectedStatus = ‘Running’ 
} 
} 


Mock Start-Service 
Mock Stop-Service 


} 


} 
'@ | Set-Content Set-ServiceState.tests.ps1 


The first path through the code, when the service is already in the expected state and neither Start-Service or Stop-Service 
will be called, can be tested using the default mocks established above. The It block can explicitly assert that Start-Service 
and Stop-Service were not called: 


It 'Service is running, expected running’ { 
Set-ServiceState -Path file.csv 
Should -Invoke Start-Service -Times @ 
Should -Invoke Stop-Service -Times @ 


The second path, when the service is stopped and should be started, can be achieved by overriding the mock for Get-Service . 
Note that the Set-ServiceState command is called again after overriding the mock: 
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It ‘Service is stopped, expected running’ { 
Mock Get-Service -MockWith { 
[PSCustomObject J@f{ 
Status = 'Stopped' 


} 


Set-ServiceState -Path file.csv 
Should -Invoke Start-Service -Times 1 
Should -Invoke Stop-Service -Times @ 


Finally, the last path runs when the service is running, but the expected state is stopped. This time the mock for Import-Csv is 
replaced: 


It ‘Service is running, expected stopped' { 
Mock Import-Csv -MockWith { 
[PSCustomObject J@f{ 
Name "servicel' 
ExpectedStatus = ‘Stopped' 


} 


Set-ServiceState -Path file.csv 
Should -Invoke Start-Service -Times @ 
Should -Invoke Stop-Service -Times 1 


These new tests should be added to the Describe block of Set-ServiceState.tests.ps1 . Once added, the tests file can be 
run with detailed output: 


a ou 


Path 
Output 


Invoke-Pester @params 
Starting discovery in 1 files. 
Discovering in C:\workspace\Set-ServiceState.tests.ps1. 
Found 3 tests. 11ms 
Discovery finished in 16ms. 
Running tests from 'C:\workspace\Set-ServiceState.tests.ps1' 
Describing Set-ServiceState 
[+] Service is running, expected running 16ms (13ms|3ms) 
[+] Service is stopped, expected running 15ms (15ms|1ms) 
[+] Service is running, expected stopped 24ms (22ms|1ms) 
Tests completed in 188ms 
Tests Passed: 3, Failed: @, Skipped: @ NotRun: @ 


These new tests provide a granular view of the different behaviors of the function. If a test fails, it is extremely easy to attribute 
cause to effect without having to spend extra time figuring out where either the tests or the subject failed. 


The examples used to demonstrate mocking so far assume that the command being mocked is available on the current system. 
Commands that are not locally installed cannot be mocked. 


Mocking non-local commands 
If a command is not available on the system running tests, the attempt to create a mock will fail. 


It is possible to work around this limitation with a small part of the command required by the tests. This can be referred to as a 
stub and typically consists of a function with only a parameter block. 


The stub is used to provide something to mock, and the mock is used to track the execution of the function and ensure a subject 
behaves as intended. 
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For example, consider a function that creates and configures a DNS zone with a predefined set of parameter values: 


function New-DnsZone { 


[CmdletBinding() ] 

param ( 
[Parameter (Mandatory) ] 
[String ]$Name 

) 

$params = @f{ 
Name = $Name 
DynamicUpdate = 'Secure' 
ReplicationScope = ‘Domain’ 

i 


$zone = Get-DnsServerZone $Name -ErrorAction SilentlyContinue 
if (-not $zone) { 
Add-DnsServerPrimaryZone @params 


It may not be desirable to install the DnsServer tools on a development system to run unit tests. To mock and verify that Add- 
DnsServerPrimaryZone is called, a function must be created first: 


Describe CreateDnsZone { 

BeforeAll { 
function Get-DnsServerZone { } 
function Add-DnsServerPrimaryZone { } 
Mock Get-DnsServerZone 
Mock Add-DnsServerPrimaryZone 

} 

It 'When the zone does not exist, creates a zone' { 
New-DnsZone -Name name 
Assert-MockCalled Add-DnsServerPrimaryZone 


Creating the function as shown here is enough to satisfy the tests, but the approach is basic. The test will pass even if parameter 
names are incorrect or missing. 


Amore advanced function to mock may be created by visiting a system with the command installed and retrieving the param 
block. The ProxyCommand type in PowerShell to get the param block from a system with the DnsServer module installed, for 
example: 


using namespace System.Management .Automation 
$command = Get-Command Add-DnsServerPrimaryZone 
[ProxyCommand] : :GetParamBlock( 

$command 


) 


For Add-DnsServerPrimaryZone the result is long. A command such as Select-Object has a simpler param block and is 
therefore easier to view. The first two parameters for Select-Object are shown here after running the GetParamBlock 
method: 


using namespace System.Management .Automation 
[ProxyCommand] : :GetParamBlock((Get-Command Select-Object) ) 
[Parameter (ValueFromPipeline=$true) | 

[psobject] 


${InputObject}, 

[Parameter (ParameterSetName='DefaultParameter', Position=0) ] 
[Parameter (ParameterSetName='SkipLastParameter', Position=@) ] 
[System.Object[ ]] 

${Property}, 
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You can use this technique to create a stub of many modules, allowing tests to run even if the module is not locally installed. 


The following snippet combines the GetParamBlock with GetCmdletBindingAttribute to create an accurate copy of the 
basics of the module to use as the basis for mocking a command. 


using namespace System.Management .Automation 
$moduleName = 'DnsServer' 
Get-Command -Module $moduleName | ForEach-Object { 
$param = [ProxyCommand]: :GetParamBlock($command) 
$param = $param -split '\r?\n' -replace '*\s{4}', '$ege' 
"function {0} {{' -f $_.Name 
{@}' -f [ProxyCommand]: :GetCmdletBindingAttribute($_) 
param (' 
$param 
)! 
y 
} | Set-Content "$moduleName.psm1" 


This approach works for the DnsServer module because the module is based on CIM classes; it only depends on assemblies 
that are already available in PowerShell. 


Adding a copy of a module will improve the overall quality of the tests for a command. Tests will fail if a non-existent parameter 
is used, or if an invalid parameter combination is used. 


Each of the mocks used so far has emitted a PSCustomObject , and in many casesa PSCustomObject is enough to use within a 
set of tests. 


Mocking objects 


Mocking allows the result of running another command to be faked. The examples in the previous section have returned a 
PSCustomObject where output is required. 


It is not uncommon for a command to expect to work with the properties and methods of another object. This might be a value 
returned by another command, or it might be the value of a parameter the test subject requires. 


The ability to mock objects or a specific type or objects that implement methods is important in testing. 
Two approaches can be taken when testing: 


e Methods can be added toa PSCustomObject 
e .NET types can be disarmed and returned 


PowerShell includes many modules that are based on CIM classes. These modules often expect CIM instances as input to work. 
Testing code that uses CIM-based commands may need to create values that closely resemble the real command output. 


Methods can be added toa PSCustomObject , allowing code that uses those methods to be tested without needing to use a more 
specific .NET type. 


Adding methods to PSCustomObject 


Objects with specific properties can be simulated by creating a PSCustomObject object: 


[PSCustomObject J@f{ 
Property = "Value" 


} 


If the subject of a test takes the result of a mocked command and invokes a method, it will fail unless the method is available. 
You can add methods toa PSCustomObject using Add-Member : 
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$object = [PSCustomObject ]@{} | 


Add-Member MethodName -MemberType ScriptMethod -Value { } 
$object 


If the method used already exists, such as the ToString method, then the -Force parameter must be used: 


$object = [PSCustomObject ]@{} 
$object | 

Add-Member ToString -MemberType ScriptMethod -Force -Value { } 
$object 


As many methods as needed can be added to the PSCustomObject as required. 


The method added to the PSCustomObject may return nothing (as in the preceding examples), return a specific value, or set a 
variable in script scope which can be tracked or tested. This idea is explored when disarming an existing .NET object. 


Disarming .NET types 


A piece of code being tested may interact with a specific .NET type. The .NET type may (by default) need to interact with other 
systems in a way that is not desirable when testing. 


The following simple function expects to receive an instance of a SqlConnection object and expects to be able to call the Open 
method: 


using namespace System.Data.SqlClient 
function Open-SqlConnection { 
[CmdletBinding() ] 
param ( 
[Parameter (Mandatory) ] 
[SqlConnection]$SqlConnection 


) 
if (¢$sqlConnection.State -eq 'Closed') { 


$SqlConnection.Open() 
} 


As the value of the SqlConnection parameter is explicitly set to accept an instance of 
System.Data.SqlClient.SqlConnection , you cannot use a PSCustomObject asa substitute. 


When running the function in a test, an instance of SqlConnection must be created to pass to the function. 


The following It block creates such an instance and passes it to the function: 


It ‘Opens an SQL connection' { 
$connection = [System.Data.SqlClient.SqlConnection] : :new() 
Open-SqlConnection -SqlConnection $connection 


This It block does not contain any assertions yet. It can assert that no errors should be thrown, but the test can only succeed if 
the computer running the tests is running an SQL server instance. By extension, the test can only fail if the computer running 
the tests is not a SQL server. 


Each of the following tests can be added toa sql.tests.ps1 file. The Describe block has been omitted from the examples to 
reduce indentation. The following command creates the tests file. All the content of the Describe block should be replaced with 
each example. 
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@' 
BeforeDiscovery { 
function Script:Open-SqlConnection { 
[CmdletBinding() ] 
param ( 
[Parameter (Mandatory) ] 
[System.Data.SqlClient .SqlConnection]$SqlConnection 
) 
if ($sqlConnection.State -eq 'Closed') { 
$SqlConnection.Open() 


} 
} 
} 
Describe Open-SqlConnection { 
if 


'@ | Set-Content sql.tests.ps1 


PowerShell code will prefer to calla ScriptMethod onan object overa Method provided by the .NET type. Therefore, a you 
can create a disarmed version of the SqlConnection object using Add-Member : 


BeforeAll { 
$connection = [System.Data.SqlClient.SqlConnection] : :new() 
¢connection | 
Add-Member Open -MemberType ScriptMethod -Value { } -Force 
} 


It ‘Opens an SQL connection’ { 
Open-SqlConnection -SqlConnection $connection 


} 


This step solves the problem of needing a SQL server to run Open , but it does not solve the problem of testing if Open was 
called. After all, the command does not return the connection object; there is no output to test. 


You can solve the problem by making the Open method do something. Possible actions include: 


e Return a value 
e Set a scoped variable 
e Set a property on the SqlConnection object 


The Open method, by default, does not return a value, and the statement that calls Open in the function is not assigned. A 
value could simply be returned by the method and tested: 


BeforeAll { 
$connection = [System.Data.SqlClient.SqlConnection] : :new() 


¢connection | 
Add-Member Open -MemberType ScriptMethod -Force -Value { 
$true 
} 
} 
It ‘Opens an SQL connection’ { Open-SqlConnection -SqlConnection $connection | 
Should -BeTrue 
} 


In some cases, such an approach might fail or become overly complex. For instance, if this is only one small step the command 
takes and there are other outputs to consider. 


Setting a variable in script scope in the mocked method will allow a test to see if the method is executed. In this case, the scoped 
value might be reset ina BeforeEach block, ensuring it is accurately recorded in each test: 
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BeforeAll { 
$connection = [System.Data.SqlClient.SqlConnection] : :new() 
¢connection | 
Add-Member Open -MemberType ScriptMethod -Force -Value { 
$Script:Opened = $true 
ii 


} 
BeforeEach { 


$Script:Opened = $false 

sp 

It ‘Opens an SQL connection’ { 
Open-SqlConnection -SqlConnection $connection 
¢Script:Opened | Should -BeTrue 


Finally, a property of the SqlConnection object might be set. The real Open method sets the value of the State property. 
This property is read-only and cannot be set directly. A NoteProperty must be added for Open to change. 


BeforeAll { 
$connection = [System.Data.SqlClient.SqlConnection] : :new() 
¢connection | 
Add-Member Open -MemberType ScriptMethod -Force -Value { 
$this.State = ‘Open' 
} 
¢connection | 
Add-Member State -NotePropertyValue Closed -Force 
i 
It ‘Opens an SQL connection' { 
Open-SqlConnection -SqlConnection $connection 
¢connection.State | Should -Be ‘Open' 


Any of the preceding options might be used when mocking methods and properties on .NET objects. 


The approach can be taken further still by using the New-MockObject command in Pester. New-MockObject creates an 
instance of a .NET type with no code behind it at all. 


New-MockObject is not appropriate in all cases. If you use this command to create the SqlConnection object used above, 
attempting to call the real Open method will always raise an error: 


n = New-MockObject System.Data.SqlClient.SqlConnection 
ion.Open() 


MethodInvocationException: Exception calling "Open" with "Ə" argument(s): "Object reference not set to 
an instance of an object." 


You can apply the techniques used in the previous examples to a wide variety of .NET objects. CimInstance objects are a 
special case when it comes to mocking. 


Mocking CIM objects 


Many modules in PowerShell are based on CIM classes. For example, the Net modules, such as NetAdapter , NetSecurity , 
and NetTCPIP , are all based on CIM classes. 


The commands in these modules either return CIM instances or include parameters that require a specific CIM instance as an 
argument. 


For example, the following function uses two of the commands in a pipeline. Any tests would have to account for the CIM 
classes when mocking commands: 
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function Enable-PhysicalAdapter { 
Get-NetAdapter -Physical | Enable-NetAdapter 


When these commands act in a pipeline, Enable-NetAdapter fills the InputObject parameter from the pipeline. Get-Help 
shows that the parameter accepts an array of CimInstance from the pipeline: 


Get-Help Enable-NetAdapter -Parameter InputObject 
-InputObject <CimInstance[ ]> 

Specifies the input to this cmdlet. You can use this parameter, or you can pipe the input to this 
cmdlet. 


Required? true 

Position? named 

Default value 

Accept pipeline input? true (ByValue) 
Accept wildcard characters? false 


However, this is not the whole story. The parameter value is further constrained by a PSTypeName attribute. This can be seen 
using Get-Command : 


$command = (Get-Command Enable-NetAdapter) 
$parameter = $command.Parameters['InputObject'] 
$attribute = $parameter.Attributes | 

Where-Object TypeId -match 'PSTypeName' 
$attribute.PSTypeName 


The result is the PSTypeName the command expects to receive from the pipeline: 


Microsoft .Management .Infrastructure.CimInstance#MSFT_NetAdapter 


Any mock for Get-NetAdapter must therefore return an MSFT_NetAdapter CimInstance object. Before the instance can be 
created, one final piece of information is required: the namespace of the CIM class. 


The namespace can be taken from any object returned by Get-NetAdapter : 


Get-NetAdapter | Select-Object CimClass -First 1 
CimClass 


ROOT/StandardCimv2:MSFT_NetAdapter 


Finally, the CimInstance object can be created using the New-CimInstance command as shown here: 


$params = @f{ 
ClassName = 'MSFT_NetAdapter' 
Namespace = ‘ROOT/StandardCimv2' 
ClientOnly = $true 

} 


New-CimInstance @params 


This instance can be added to a mock for Get-NetAdapter when testing the Enable-PhysicalAdapter command: 
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BeforeDiscovery { 
function Script:Enable-PhysicalAdapter { 
Get-NetAdapter -Physical | Enable-NetAdapter 


} 


} 
Describe Enable-PhysicalAdapter { 


BeforeAll { 
Mock Enable-NetAdapter 
Mock Get-NetAdapter { 


$params = @{ 
ClassName = 'MSFT_NetAdapter' 
Namespace = 'ROOT/StandardCimv2' 
ClientOnly = $true 

} 


New-CimInstance @params 


} 


} 
It ‘Enables a physical network adapter’ { 


{ Enable-PhysicalAdapter } | Should -Not -Throw 
Should -Invoke Enable-NetAdapter -Times 1 


The commands used in each of the tests in this section are expected to be available in the global scope so that Pester can mock 
and run the commands. Pester is also able to test commands and classes that are not exported from a module. 


InModuleScope 


The InModuleScope command and the -ModuleName parameter of Should and Mock are important features of Pester. The 
command and parameters allow access to content that is normally in the module scope and inaccessible outside. 


The following two commands were first introduced in Chapter 20, Building Modules: 


@' 
function GetRegistryParameter { 
[CmdletBinding() ] 
param ( ) 
@{ 
Path = 'HKLM:\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters ' 
Name = 'srvcomment' 
} 
} 
function Get-ComputerDescription { 
[CmdletBinding() ] 
param ( ) 
$getParams = GetRegistryParameter 
Get-ItemPropertyValue @getParams 
} 


Export-ModuleMember Get-ComputerDescription 
'@ | Set-Content LocalMachine.psm1 


The function GetRegistryParameter can be tested in Pester by using InModuleScope : 
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@' 
BeforeDiscovery { 
Import-Module .\LocalMachine.psm1 -Force 
j 
Describe GetRegistryParameter { 
It 'Returns a hashtable' { 
InModuleScope -ModuleName LocalMachine { 
GetRegistryParameter 
} | Should -BeOfType [Hashtable] 
i 


ji 
'@ | Set-Content GetRegistryParameter.tests.ps1 


If the InModuleScope command is omitted, the test will fail and the GetRegistryParameter function is not exported from the 
module and is therefore not normally accessible. 


The result of running the tests is shown here: 


Invoke-Pester -Script .\GetRegistryParameter.tests.ps1 
Starting discovery in 1 files. 
Discovery finished in 227ms. 


Running tests. 

[+] C:\workspace\GetRegistryParameter.tests.ps1 1.04s (152ms|7@2ms) 
Tests completed in 1.06s 

Tests Passed: 1, Failed: @, Skipped: © NotRun: @ 


A test document may include more than one use of InModuleScope , but it is advisable to keep the size of these blocks as small 
as possible. InModuleScope should not be used to enclose Describe, Context , and It. 


In the same way, if it were desirable to mock that command when testing the Get-ComputerDescription command, the - 
ModuleName parameter is required for the Mock keyword: 


BeforeAll { 
Mock GetRegistryParameter -ModuleName LocalMachine 


InModuleScope can be used to access anything in the module scope, including private commands, classes, and enumerations, 
and any module-scoped variables. 


Pester in scripts 

Using InModuleScope can add complexity when running Invoke-Pester from a script. 

When Invoke-Pester is run from a global scope, -ModuleName is only required to access private components of a module. 
When Invoke-Pester is run from a script, problems may surface because the script scope breaks Pester's scoping. 


Consider the following tests: 
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@' 
BeforeDiscovery { 

Import-Module .\LocalMachine.psm1 -Force 
} 
Describe Get-ComputerDescription { 

BeforeAll { 

Mock Get-ItemPropertyValue { 
"Mocked description’ 


} 


It ‘Returns the mocked description’ { 
Get-ComputerDescription | 
Should -Be 'Mocked description' 
Should -Invoke Get-ItemPropertyValue 
} 


} 
'@ | Set-Content Get-ComputerDescription.tests.ps1 


When Invoke-Pester is run from the console, the tests pass provided the LocalMachine module was successfully imported: 


Invoke-Pester -Path .\Get-ComputerDescription.tests.ps1 
Starting discovery in 1 files. 
Discovery finished in 7ms. 


[+] C:\workspace\Get-ComputerDescription.tests.ps1 98ms (6ms|86ms) 
Tests completed in 99ms 
Tests Passed: 1, Failed: ©, Skipped: © NotRun: @ 


If instead the Invoke-Pester command is put in a script, and the script is run the mock is completely ignored: 


@' 
Invoke-Pester -Path .\Get-ComputerDescription.tests.ps1 
'@ | Set-Content script.ps1 


This is shown here when running the script: 


.\script.ps1 
Starting discovery in 1 files. 
Discovery finished in 7ms. 
[-] Get-ComputerDescription.Returns the mocked description 5ms (4ms|1ms) 
PSArgumentException: Property srvcomment does not exist at path 


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanServer\Parameters. 
at Get-ComputerDescription, C:\workspace\LocalMachine.psm1:16 
at <ScriptBlock>, C:\workspace\Get-ComputerDescription.tests.ps1:12 

Tests completed in 117ms 

Tests Passed: ©, Failed: 1, Skipped: © NotRun: @ 


To work around this problem, the -ModuleName parameter must be added to all Mock commands and all Should -Invoke 
assertions. In the following example, a splat is used: 
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Describe Get-ComputerDescription { 
BeforeAll { 
$module = @f{ 
ModuleName = 'LocalMachine' 
} 
Mock Get-ItemPropertyValue @module { 
'Mocked description' 
I; 
} 


It ‘Returns the mocked description’ { 
Get-ComputerDescription | 
Should -Be 'Mocked description’ 
Should -Invoke Get-ItemPropertyValue @module 


In all cases the module name is the scope the mock should be created in, so the subject module, not the module the mocked 
command belongs to. 


With this in place, Invoke-Pester can be run from a script: 


.\script.ps1 
Starting discovery in 1 files. 
Discovery finished in 23ms. 


[+] C:\workspace\Get-ComputerDescription.tests.ps1 135ms (25ms|88ms) 
Tests completed in 137ms 
Tests Passed: 1, Failed: @, Skipped: © NotRun: @ 


Pester is a wonderful tool for writing tests for a variety of different purposes. The tools above offer an introduction to the 
capabilities of the module. 


Summary 


This chapter explored the complex topic of testing in PowerShell. 


Static analysis is one part of testing and is the approach used by modules like PSScriptAnalyzer . Static analysis makes use of 
the Abstract Syntax Tree and tokenizers in PowerShell. 


The Abstract Syntax Tree or AST describes the content of a block of code as a tree of different elements, starting with a 
ScriptBlockAst at the highest level. You can use the ParseInput and ParseFile methods of the Parser type to get either 
an instance of the AST for a piece of code or the tokens that make up a script that includes comments. 


The ShowPSAst module can be used to visualize and explore the AST tree. ShowPSAst is a useful tool when starting to work 
with AST as the tree can quickly become complex. 


PSScriptAnalyzer uses either AST or tokens to define rules. Rules can be used to test and enforce personal or organization- 
specific practices. 


Pester is a testing framework and this chapter explored both acceptance and unit testing. 


Acceptance testing is commonly used to assess the state of systems and services. You can use Pester to define tests, which can be 
saved and shared. Such tests can be used to validate a system is configured or behaving as it should be. 


Pester is a rich tool that supports iteration with the -ForEach or -TestCases parameters. Conditional testing can be achieved 
using the Set-ItResult and -Skip parameters. 


Mocking is an exceptionally useful feature of Pester and is often used when writing unit tests to reduce the amount of code that 
must be tested when the subject is a single command. 


The next chapter explores error handling in PowerShell, including terminating and non-terminating errors and the use of try , 
catch, finally , andthe trap statement. 
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22 
Error Handling 


Errors communicate unexpected conditions and exceptional circumstances. Errors often contain useful information that you can 
use to diagnose a condition. 


PowerShell has two different types of errors, terminating and non-terminating, and several different ways to raise and handle 
them. 


Error handling in PowerShell is a complex topic, which is not helped by incorrect assertions in help documentation surrounding 
terminating errors. These challenges are explored in this chapter. 


Self-contained blocks of code are described as scripts in this chapter. That is, functions, script blocks, and scripts can be 
considered interchangeable in the context of error handling. 


This chapter covers the following topics: 


e Error types 
e Error actions 
e Raising errors 


e Catching errors 


Error types 


As mentioned above, PowerShell defines two different types of errors: terminating and non-terminating errors. 


Each command in PowerShell may choose to raise either of these, depending on the operation. 


Non-terminating errors 


Anon-terminating error, a type of informational output, is written without stopping a script. Non-terminating errors exist to 
allow a command to continue in the event of a partial failure. For example, if a command is acting on a pipeline and one item 
fails, the command can write an error and continue to process the remaining items. 


Non-terminating errors can be written using the Write-Error command, although a deeper analysis of this approach and 
alternatives are explored later in this chapter. 


The following example demonstrates how a non-terminating error can be used in a function accepting pipeline input: 


function Update-Value { 
[CmdletBinding() ] 
param ( 
[Parameter(Mandatory, ValueFromPipeline) ] 
[string]$Value 
) 
process { 
if (¢$Value.Length -1t 5) { 
Write-Error (‘The value {ð} is unacceptable’ -f $Value) 
} else { 
"Updated value: {0}' -f $Value 


} 
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When executed on a pipeline containing words, the command will write an error and continue every time it encounters a word 


with a length less than 5 : 


PS> 'value', 'val', ‘longvalue' | Update-Value 
Updated value: value 


Update-Value: The value val is unacceptable 
Updated value: longvalue 


Scenarios like this are why non-terminating errors exist. It is then up to the consumer of the command to decide if a script 
should continue. 


Non-terminating errors should be used when a script acts on more than one input, and an error for a single item does not affect 
success or failure for subsequent items. 


Terminating errors are used to stop a script in the event of a problem. 


Terminating errors 


Terminating errors are used to stop an operation from continuing. 


Terminating errors split in two depending on how the error is raised; this leads to some inconsistent behavior, which is explored 
in the Raising errors section later in this chapter. 


A terminating error stops a script once an error is thrown. No further commands will execute after the error is thrown. 


When running the following command, the second Write-Host statement will never execute: 


function Stop-Command { 
Write-Host 
throw 
Write-Host 


Running the function will show that the second Write-Host command does not execute: 


PS> $ErrorActionPreference = ‘Continue’ 
PS> Stop-Command 

First 

Exception: 


Line | 
3 | throw ‘Error’ 


| RRR 


| Error 


The assertion that the second statement will never run has a caveat, terminating errors raised by throw are affected by the 
$ErrorActionPreference variable. This is the reason for ensuring $ErrorActionPreference is set to Continue before 
running the last example. 


Setting the ErrorAction to SilentlyContinue shows that the error is ignored: 


PS> $ErrorActionPreference = 'SilentlyContinue' 
PS> Stop-Command 


First 
Second 


This contradicts the statements in the PowerShell documentation: 


e Get-Help about_Throw asserts that the throw keyword causes a terminating error 


e Get-Help about_Preference Variables asserts that $ErrorActionPreference and -ErrorAction do not affect 
terminating errors 
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Exactly how this affects code and how to create code that behaves consistently are explored in this chapter. 


Before exploring raising errors in PowerShell, the ErrorActionPreference variable and -ErrorAction parameters should be 
introduced. 


Error actions 


The -ErrorAction parameter and the ErrorActionPreference variable are used to control what happens when a non- 
terminating error is encountered, subject to the previous notes about throw . 


The -ErrorAction parameter is made available on a command when the CmdletBinding attribute is present. The 
CmdletBinding attribute is implicitly added if one or more parameters in a script use the Parameter attribute. 


By default, -ErrorAction is set to Continue . Non-terminating errors will be displayed, but a script will continue to run. 


$ErrorActionPreference isa scoped variable, which you can use to affect all commands in a particular scope and any child 
scopes. By default, $ErrorActionPreference is set to Continue . You can override the variable in child scopes (such as a 
function inside a script). 


All errors in a session are implicitly added to the reserved variable $Error unless the error action is set to Ignore . Now, 
$Error is an ArrayList and contains each error in the session with the newest first (at index 0). 


If -ErrorAction isset to SilentlyContinue , errors will still be added to the $Error automatic variable, but the error will not 
be displayed in the host. 


The following function writes a non-terminating error using Write-Error : 


function Start-Task { 
[CmdletBinding()] 
param ( ) 


Write-Error ‘Something went wrong' 


} 


Start-Task -ErrorAction SilentlyContinue 
The error is not displayed in the host or console, the error may be viewed as the latest entry in the $Error variable: 


rror[@] 


Start-Task: Something went wrong 


If the error action is set to Stop , a non-terminating error becomes a terminating error. In the console, the output in either case is 
similar. However, a terminating error is displayed differently when viewing $Error[@] : 


PS> Start-Task -ErrorAction Stop 

Start-Task: Something went wrong 

PS> $Error[e@] 

ErrorRecord : Something went wrong 

WasThrownFromThrowStatement : False 

TargetSite : System.Collections.ObjectModel.Coll 
ection 1[System.Management .Automati 
on.PSObject] Invoke(System.Collecti 
ons. IEnumerable) 

StackTrace : at System.Management.Automation. 
Runspaces.PipelineBase. Invoke(IEnum 
erable input) 

at System.Management .Automation. 
Runspaces.Pipeline. Invoke() 

at Microsoft.PowerShell.Executor 
. ExecuteCommandHelper (Pipeline 
tempPipeline, Exception& 
exceptionThrown, ExecutionOptions 
options) 

Message : The running command stopped 
because the preference variable 
"ErrorActionPreference” or common 
parameter is set to Stop: 

Something went wrong 

Data : {System.Management .Automation. Inter 
preter. InterpretedFrameInfo} 

InnerException 

HelpLink 

Source : System.Management . Automation 

HResult : -2146233087 


The content of the object is difficult to read, especially in a narrow console. 


PowerShell 7 includesa Get-Error command, which you can use to explore errors that have been raised in greater detail. 


About Get-Error 


The Get-Error command was introduced with PowerShell 7. When used without any parameters, it gets the latest error from 
the $Error variable and provides a summary of the content of that error. 


If the Start-Task function above is executed, Get-Error can be used to explore the details of the error it raised. 
The output differs between terminating and non-terminating errors, more information is shown for terminating errors. 


Figure 22.1 shows the output of the command when a non-terminating error has been written; the content does not display well 
in a narrow console: 
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unction Start-Task 
[CmdletBindingQ ] 
param ( ) 


Write-Error ‘Something went wrong’ 
C:\> Start-Task 


C:\> Get-Error 


Microsoft.PowerShel].Commands.WriteErrorException 
Message : Something went wrong 
HResult : -2146233087 
CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException 
FullyQualifiedErrorId : Microsoft.PowerShel1].Commands .WriteErrorException, Start-Task 
Invocationinfo - 
MyCommand : Start-Task 
ScriptLineNumber : 1 
OffsetInLine Sl 
HistorylId AY. 
Line : Start-Task 
PositionMessage : At line:1 char:1 
+ Start-Task 
~~ ANA 
InvocationName : Start-Task 
CommandOrigin : Internal 
ScriptStackTrace : at Start-Task, <No file>: line 5 
at <ScriptBlock>, <No file>: line 1 
PipelineIterationinfo : 


Figure 22.1: Get-Error command 


You can use Get-Error to view the last error, a user-defined number of the newest errors, and a specific error using 
ErrorRecord . 


For example, if $Error contained 10 errors, and only one of those from the middle of the set was of interest, Get-Error would 
accept one or more errors as pipeline input: 


$Error[4] | Get-Error 


If there were fewer than 4 errors, another error would be written. 


When writing scripts, it is often desirable to write or raise an error. 


Raising errors 


When writing a script, it may be desirable to use errors to notify the person running the script of a problem. The severity of the 
problem will dictate whether an error is non-terminating or terminating. 


If a script makes a single change to many diverse, unrelated objects, a terminating error might be frustrating for anyone using 
the script. 


On the other hand, if a script fails to read a critical configuration file, a terminating error is likely the right choice. 


Error records 


When an error is raised in PowerShell, an ErrorRecord object is created (explicitly or implicitly). 


An ErrorRecord object contains several fields that are useful for diagnosing an error. ErrorRecord can be explored using 
Get-Member or by using the Get-Error command. 


For example, an ErrorRecord will be generated when attempting to divide by 0: 
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100 / © 
$record = $¢Error[@] 


The ErrorRecord object that was generated includes ScriptStackTrace , which includes the script names that were called 
and the position where an error occurred. ScriptTrackTrace is extremely useful when debugging problems in larger scripts: 


ScriptStackTrace 


at <ScriptBlock>, <No file>: line 1 


A bespoke ErrorRecord can be created within a script to more clearly describe a problem to the user. The error record might 
include additional information to assist with debugging. 


For example, if the values for a division operation were dynamically set, an ErrorRecord might be created to include those 
values in the TargetObject to assist with debugging: 


using namespace System.Management .Automation 
g$numerator = 10 
$denominator = @ 
try { 
g$numerator / $denominator 
} catch { 
gerrorRecord = [ErrorRecord]: :new( 
[Exception]: :new($_.Exception.Message), 
"InvalidDivision', 
"InvalidOperation', 
[PSCustomObject J@f{ 
Numerator = $numerator 
Denominator = $denominator 
} 
) 


Write-Error -ErrorRecord $errorRecord 


The ErrorRecord object and the constructor in the preceding example are described on Microsoft Docs: 
https://docs.microsoft.com/dotnet/api/system.management.automation.errorrecord.-ctor? 


view=powershellsdk- 
7.0.0#System_Management_Automation_ErrorRecord_ ctor System Exception System String System Manag 
ement_Automation ErrorCategory System Object . 


The values added to the ErrorRecord may be viewed by exploring the TargetObject property: 


KIRENA 
Numerator Denominator 


The try-catch statement used in the previous example is covered in detail while exploring try, catch , and finally later 
in this chapter. 


Raising non-terminating errors 


You can use the Write-Error command to write a non-terminating error message. 


The Write-Error command can display a simple message: 
Write-Error -Message ‘Message’ 


Or the error might include additional information, such as a category and error ID to aid diagnosis by the person using the 
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script: 
$params = @f{ 
Message = ‘Message’ 
Category = 'InvalidOperation' 
ErrorID = '‘UniqueID' 
J 


Write-Error @params 
The following example shows a non-terminating error that was raised while running a loop: 


function Test-Error { 
[CmdletBinding() ] 
param ( ) 
for ($i = 0; $i -lt 3; $i++) { 
Write-Error -Message "Iteration: $i" 


When the function runs, an error is displayed three times without stopping execution: 


Test-Error 
Test-Error: Iteration: @ 


Test-Error: Iteration: 1 
Test-Error: Iteration: 2 


Setting the value of ErrorAction to Stop will cause Write-Error to throw a terminating error, ending the function within 
the first iteration of the loop: 


Test-Error -ErrorAction Stop 
Test-Error: Iteration: @ 


Alternatively, the error can be silenced ( SilentlyContinue ) or ignored ( Ignore ), depending on the importance of the error to 
the user of the function. 


One disadvantage of using the Write-Error command is that it does not set the value of the automatic variable $? unless 
ErrorAction is set to Stop . The variable $? isset to True if the last command was successful, or False if the last 
command failed: 


Test-Error 
Test-Error: Iteration: @ 
Test-Error: Iteration: 1 


Test-Error: Iteration: 2 
$? 


True 


The WriteError method may be used as an alternative to the Write-Error command. 


Using the WriteError method 


The WriteError method is used by binary commands and can optionally be used by scripts, provided the script includes the 
CmdletBinding attribute. 


The presence of the CmdletBinding attribute makes the $PSCmdlet variable available for use within a script. The $PSCmdlet 
variable provides access to the WriteError method. 


The WriteError method requires an ErrorRecord as an argument as shown in the following example: 
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using namespace System.Management .Automation 
function Test-Error { 
[CmdletBinding() ] 
param ( ) 
for ($i = 0; $i -lt 3; $i++) { 
$gerrorRecord = [ErrorRecord]: :new( 
[Exception]::new('Iteration {0}' -f $i), 
"InvalidOperation', 
"InvalidOperation' , 
$i 
) 
$PSCmdlet .WriteError($¢errorRecord) 


When running the command, the value of $? correctly reflects that one or more errors occurred in the last command: 


Test-Error 
Test-Error: Iteration @ 
Test-Error: Iteration 1 


Test-Error: Iteration 2 
$? 


False 


You can raise terminating errors by setting -ErrorAction to Stop when using the Write-Error command. However, it is 
often more appropriate to explicitly raise a terminating error. 


Raising terminating errors 


The throw keyword raises a terminating error, as in the following example: 
throw 'Error message’ 


Existing exception types are documented in .NET Framework; each is ultimately derived from the System.Exception type 
found in the .NET reference: https: //docs.microsoft.com/dotnet/api/system. exception 


throw may be used with a string or a message, as shown previously. throw may also be used with an exception object: 
throw [ArgumentException]::new( ‘Unsupported value’) 
Or you can use throw with ErrorRecord : 


using namespace System.Management .Automation 

throw [ErrorRecord]: :new( 
[InvalidOperationException]::new('Invalid operation'), 
"AnErrorID', 
[ErrorCategory ]::InvalidOperation, 
$null 


Commands in binary modules cannot use throw ; it has a different meaning in the languages that might be used to author a 
cmdlet (such as C#, VB, or F#). Cmdlets use the ThrowTerminatingError method instead. 


Using the ThrowTerminatingError method 


Like the WriteError method, ThrowTerminatingError is made available to scripts that use the CmdletBinding attribute 
The ThrowTerminatingError method is available on the $PSCmdlet variable. 


The ThrowTerminatingError method requires an ErrorRecord object as shown in the following example: 
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using namespace System.Management .Automation 
function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 


gerrorRecord = [ErrorRecord]: :new( 
[InvalidOperationException]::new('Failed'), 
‘AnErrorID' , 
[ErrorCategory]: :OperationStopped, 
$null 

) 


$PSCmdlet . ThrowTerminatingError ($errorRecord) 


Running the command will show this simple error message: 


Invoke-Something 


Invoke-Something: Failed 


More detailed error information can be viewed using the Get-Error command. 


An error may only exist to communicate a problem to an end user, but it is common to need to capture and handle errors in 
another script. 


Catching errors 


Capturing an error so that a script can react to that error depends on the error type. 


e Non-terminating errors can be captured by using ErrorVariable 


e Terminating errors can be captured using eithera try, catch, and finally statement, or by using a trap statement 


The -ErrorVariable parameter can be used to create a scoped alternative to the $Error variable. 


ErrorVariable 


The $Error variable is a collection (ArrayList) of handled and unhandled errors raised in the PowerShell session. 


You can use the -ErrorVariable parameter to name a variable that should be used for a specific script. The ErrorVariable 
accepts the name of a variable and is created as an Array List. 


The following function writes a single error using the Write-Error command: 


function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 


Write-Error 'Invoke-Something Failed' 


The command can be run using the -ErrorVariable parameter. The -ErrorAction parameter below is used to suppress the 
normal error output: 


$params = @f{ 
ErrorVariable = 'MyErrorVariable' 
ErrorAction = 'SilentlyContinue' 
} 


Invoke-Something @params 
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Nothing is displayed in the console, but the error is added to $MyErrorVariable : 


Invoke-Somethi : Invoke-Something Failed 


Error messages written toan -ErrorVariable are duplicated in $Error . 


An -ErrorVariable is never null 
If no errors occur, a variable will still be created as an ArrayList, but the list will contain no elements. 


The Count property might be inspected to see if any errors occurred: 


$MyErrorVariable.Count -eq @ 


Asingle -ErrorVariable can be shared by several different scripts; by default the content of the variable is overwritten. If + is 
added to the beginning of the variable name, then new errors will be added without overwriting the content of the variable. The 
following command is run twice: the first run creates a new error variable, and the second adds to that existing variable: 


Invoke-Something -ErrorVariable MyErrorVariable 
Invoke-Something -ErrorVariable +MyErrorVariable 


Once the two commands have finished, $MyErrorVariable will contain two errors, one from each command. 


Terminating errors are most frequently handled using try, catch,and finally . 


try, catch, and finally 


PowerShell 2.0 introduced try, catch, and finally asa means of handling terminating errors. 
try cannot be used alone; it must be used with either catch, finally , or both. 


The most used statement isa try followed by a single catch: 


try { 
throw ‘An error' 


} catch { 
Write-Host 'Caught an error’ 


} 


The catch block only executes if an error is raised; a terminating error will stop the script enclosed by try at the point the 
error is thrown. 


Inside the catch block, the variable $_ (or $PSItem ) is set tothe ErrorRecord that caused catch to trigger. This is 
important if a command such as ForEach-Object is used; the original pipeline variable is not accessible inside the catch 
block. 


The ErrorRecord hasan Exception property, and the Exception hasa Message property. These values were seen when 
looking at the output from Get-Error . These values, and any other properties of the ErrorRecord , may be accessed using the 
$_ variable as the following code shows: 


thy {i 
1/0 
} catch { 
Write-Host $ _.Exception.Message 


} 


In this example, the catch statement reacts if any exception type is thrown. The statement is equivalent to the following: 
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try A 
1/0 
} catch [Exception] { 
Write-Host $_.Exception.Message 


} 
catch can be used to react to a more specific exception type instead: 


thy a 

throw [ArgumentException]::new('Invalid argument’ ) 
} catch [ArgumentException] { 

Write-Host ‘Caught an argument exception’ 


} 
More than one catch statement can be supplied, allowing different reactions to different types of error: 


try { 

throw [ArgumentException]::new('Invalid argument’) 
} catch [InvalidOperationException] { 

Write-Host ‘Caught an invalid operation exception’ 
} catch [ArgumentException] { 

Write-Host 'Caught an argument exception’ 


} 


The catch statements are evaluated in the order they are written. The most specific handlers should be written before more 
general error types: 


try { 

throw [ArgumentException]::new('Invalid argument’) 
} catch [ArgumentException] { 

Write-Host 'Caught an argument exception’ 
} catch { 

Write-Host ‘Something else went wrong' 


} 
Each catch statement can be triggered by one or more exception types: 


‘try { 
throw [ArgumentException]::new('Invalid argument’) 

} catch [InvalidOperationException], [ArgumentException] { 
Write-Host ‘Argument or InvalidOperation exception’ 


} 


The finally block and be used either alongside or instead of catch . The finally block always executes, even if an error 


occurred during try . The finally block is therefore an ideal place to clean up anything that might otherwise cause a 
problem. 


In the following example, finally is used to close a potentially open connection to an SQL server: 
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using namespace System.Data.SqlClient 
$connectionString = ‘Data Source=dbServer; Initial Catalog=dbName' 
CRY 
$sqlConnection = [SqlConnection]: :new($connectionString) 
$sqlConnection.Open() 
$sqlCommand = $sqlConnection.CreateCommand() 
$sqlCommand.CommandText = 'SELECT * FROM Employee’ 
$reader = $sqlCommand.ExecuteReader() 
} finally { 
if (¢$sqlConnection.State -eq ‘Open') { 
$sqlConnection.Close() 
} 


When catch is used with finally , the content of finally is executed before errors are returned, but after the body of 
catch has executed. This is demonstrated by the following example: 


try { 
Write-Host "Try" 
throw ‘Error’ 
} catch { 
Write-Host "Catch, after Try” 
throw 
} finally { 
Write-Host "Finally, after Catch, before the exception" 


} 


An error raised in try canbe repeated ina catch block. 


Rethrowing errors 


Errors may be caught using try , then thrown again (or rethrown) ina catch block. This technique can be useful if a try 
block performs several dependent steps in a sequence where one or more might fail. 


Rethrowing an error raised by a script can be as simple as using throw ina catch block: 


try {i 
"Statement1' 


throw 'Statement2' 
"Statement3' 

} catch { 
throw 


} 


The previous example will display Statement1 , then the error. Statement3 will never run in this case. 


You can use ThrowTerminatingError to emit the error record that catch is handling: 


function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 
try { 
"Statement1' 
throw 'Statement2' 
"Statement3' 
} catch { 
$pscmdlet.ThrowTerminatingError($_) 


} 
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When an error is rethrown in the manner shown above, the second instance of the error (within the catch block) is not written 


to either $Error or a user-defined error variable. If the error is not modified, this is not a problem. 


If information is added to the error before it is rethrown, such as an error ID, the modified error record will not be available to 
error variables. This is shown in the following example: 


ty 
throw 'Error' 
} catch { 
$params = @{ 
Exception = $ .Exception 
ErrorID = '‘SomeErrorID' 
Category = ‘InvalidOperation' 
} 


Write-Error @params 


Get-Error can be used to show that the category and ErrorID are not set as defined in the catch block for the last error 
raised: 


Get-Error | 
Select-Object CategoryInfo, FullyQualifiedErrorId | 
> Format-List 


CategoryInfo : OperationStopped: (Error:String) [], 
RuntimeException 
FullyQualifiedErrorId : Error 


The preceding problem can be resolved by creating a new error record with the original exception as an inner exception: 


tyd 
throw ‘Error’ 
} catch { 
$params = @{ 

Exception = [InvalidOperationException]: :new( 
$_.Exception.Message, 
$_.Exception 

) 

ErrorID = 'SomeErrorID' 

Category = ‘InvalidOperation' 

i; 


Write-Error @params 


In the case of the preceding exception and most exception types, the first argument of the constructor is a message, and the 
second (optional) argument is an inner exception. 


Inner exception types cannot be used with catch statements in PowerShell except when a MethodInvocationException is 
raised. 


A MethodInvocationException is a generic error that is raised when PowerShell executes a method on a .NET type or object: 


[DateTime]: :DaysInMonth(2019, 13) 
Get-Error | ForEach-Object { 
$_.Exception.GetType().Name 


PowerShell can react to the MethodInvocationException type 
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using namespace System.Management .Automation 


try 
[DateTime]: :DaysInMonth(2019, 13) 


} catch [MethodInvocationException] { 
Write-Host 'Caught a method invocation exception’ 


However, this exception type is not particularly useful. In the case of a MethodInvocationException PowerShell can catch the 
inner exception, in this case an ArgumentOutOfRange exception: 


try { 
[DateTime]: :DaysInMonth(2019, 13) 


} catch [ArgumentOutOfRangeException] { 
Write-Host ‘Out of range’ 


When a command raises an error, the actual problem may be nested under one or more inner exceptions. When only the inner 
exception is interesting, you can use InnerException . It allows access to each inner exception in turn. In the following example, 
the property is used to access the exception in the middle: 


try A 
throw [InvalidOperationException] : :new( 


"OuterException', 

[ArgumentException] : :new( 
"IntermediateException', 
[UnauthorizedAccessException] : :new('InnerException' ) 


) 
} catch { 
Write-Host $_.Exception.InnerException.Message 


The Exception class (and all derived classes) include a GetBaseException method. This method provides simple access to the 
inner-most exception and is useful when the number of nested exceptions is unknown: 


toy a 
throw [InvalidOperationException]: :new( 


"OuterException', 

[ArgumentException] : :new( 
"IntermediateException', 
[UnauthorizedAccessException] : :new('InnerException' ) 


) 
} catch { 
Write-Host $_.Exception.GetBaseException().Message 


In cases where the exception type is not sufficient, the catch block can be expanded to include if or switch statements, 
allowing decisions to be made based on values like the message in an exception. 


At the start of this chapter, a reference was made to incorrect documentation surrounding terminating errors. 


Inconsistent error handling 


The different methods PowerShell exposes to create a terminating error are not consistent and can be extremely confusing. 


The behavior of the different types of error is explored in detail in an issue in the PowerShell Docs repository: 
https://github.com/MicrosoftDocs/PowerShell-Docs/issues/1583. 


Unfortunately, the content of the thread is yet to find a home in released documents. 
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When. throw is used to raise a terminating error, the current script, and anything that called the current script, is stopped. The 


preceding link refers to errors raised by throw asa script-terminating error. 


Ascript-terminating error is shown in the following example: 


$ErrorActionPreference = ‘Continue’ 
function caller { 
first 
second 
} 
function first { 
throw 'Failed' 


Girst: 

} 

function second { 
"second' 

} 


The error raised in the function named first stops all commands in the chain. The function named second is never executed. 
This is shown when the function caller is run: 


caller 
Exception: 
Line | 


2 | throw 'Failed' 


| TTT IIIT 


| Failed 


This differs from the behavior when ThrowTerminatingError is called. ThrowTermatingError is used by binary modules that 
want to stop execution; this introduces a rift in error handling between script and binary modules. 


The article linked at the beginning of this section refers to an error raised by ThrowTerminatingError as a statement- 
terminating error: 


using namespace System.Management .Automation 
function caller { 
first 
second 
} 
function first { 
[CmdletBinding() ] 
param ( ) 


gerrorRecord = [ErrorRecord]: :new( 
[Exception]: :new('Failed'), 
“TDI, 
"OperationStopped' , 
$null 
) 
$pscmdlet. ThrowTerminatingError($errorRecord) 
Papal ee 
i 
function second { 
"second' 


Running the function first shows a different result to the version that used a throw statement instead: 


first: 
Line | 


2 | first 
| E 


| Failed 
Second 


The ThrowTerminatingError statement stops the function first from completing, but it does not stop the function caller 
from continuing. 


This second version is therefore consistent with a script that runs a command from a binary module. In the following example, 
ConvertFrom-Json raises a terminating error but does not stop the function that called it from executing: 


function caller { 
ConvertFrom-Json -InputObject '{{' 


second 

} 

function second { 
"second' 

} 


The output when running caller is: 


ConvertFrom-Json: 
Line | 
2 | ConvertFrom-Json -InputObject '{{' 


| RRR NNN 


| Conversion from JSON failed with error: Invalid property identifier character: {. Path '', line 
1, position 1. 
second 


The same behavior is seen when calling .NET methods. The static method, IPAddress .Parse , will raise an exception because 
the use of the method is not valid. The function continues from this error and calls the function second : 


function caller { 
[IPAddress]::Parse('this is not an IP') 
child1 


} 
function second { 
"second' 


} 


caller 


Not only do errors raised by throw differ from those raised by ThrowTerminatingError , but throw statements are also 
influenced by the error action preference despite the documentation for PowerShell having stated the opposite for the last 
decade 


throw and ErrorAction 


The throw keyword raises a terminating error; terminating errors are described in about_Preference_Variables as not 
being affected by the ErrorActionPreference . 


Unfortunately, errors raised by throw are affected by ErrorAction when ErrorAction is set to SilentlyContinue . This 
behavior is an important consideration when designing commands for others to use. 


The following function throws a terminating error; the second statement should never run: 
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function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 


throw ‘Error' 
Write-Host 'No error' 


Running the function with an error action set to the default, continue , shows that the error is thrown and the second 
command does not execute: 


Invoke-Something 
Exception: 
Line | 


5 | throw ‘Error’ 


| RRR 


| Error 


If ErrorAction is set to SilentlyContinue , throw will be ignored: 


Invoke-Something -ErrorAction SilentlyContinue 
No error 


The same problem exhibits of the $ErrorActionPreference variable is set in the parent scope: 


nvoke-Something 
No error 


You can still usea throw statement in a script, but because it does not behave as described in the documentation it must be 
used with great care. 


Enclosing a throw statementina try block will cause it to trigger catch , ending the script as it should regardless of the 
ErrorAction setting: 


function Invoke-Something { 
[CmdletBinding()] 
param ( ) 
tey 7A 
throw ‘Error’ 
Write-Host 'No error' 
} catch { 
Write-Host ‘An error occurred’ 


When the function is called, the content of the catch block executes as it should: 


Invoke-Something -ErrorAction SilentlyContinue 


An error occurred 


The problem described here also applies when throw is used within the catch block, although, in this case, the script still 
terminates. 


The following script should result in an error being displayed as the error is terminating; however, no error is displayed if you set 
-ErrorAction to SilentlyContinue . The error raised in try does still prevent the script from progressing to the Write- 
Host command: 
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function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 


try { 
throw ‘Error' 


Write-Host 'No error' 
} catch { 
throw ‘An error occurred' 


In this version, any statements that appear after the throw statement in the catch block will not execute. When - 
ErrorAction is set to SilentlyContinue , this function runs and returns nothing at all. The only evidence of an error is in the 
$Error variable: 


or .Clear() 
nvoke-Something -ErrorAction SilentlyContinue 
[@] 


Exception: 


Line | 
9 | throw 'An error occurred’ 


| RRR 


| An error occurred 


For scripts that use the CmdletBinding attribute, ThrowTerminatingError can be used. The ThrowTerminatingError 
method is not affected by the -ErrorAction parameter or $ErrorActionPreference variable: 


function Invoke-Something { 
[CmdletBinding() ] 
param ( ) 


try {i 
throw ‘Error' 


Write-Host 'No error' 
} catch { 
$PSCmdlet.ThrowTerminatingError($_) 


Running the command shows will reliably show the error. The error can be handled by usinga try statement in the script 
calling this command: 


Invoke-Something -ErrorAction SilentlyContinue 


Exception: Error 


To establish consistent behavior, the following recommendations can be made: 


e Prefer to use CmdletBinding with functions, scripts, and ScriptBlocks 

e When using throw, only use throw inside try block 

e Use the ThrowTerminatingError method to stop a script from executing 

e Prefer the WriteError method when creating non-terminating errors as this correctly sets the value for $? 


e Any script that calls another that may raise an error should expect and handle errors using a try block 


To provide more granular error handling in a script, you can nest try blocks. 


Nesting try, catch, and finally 


One try statement can be inside another to provide granular error handling of small operations. 
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Ascript that performs setup actions and then works on several objects in a loop is a good example of a script that might benefit 


from more than one try statement. The script should terminate cleanly if something goes wrong during setup, but it might 
only notify if an error occurs within the loop. 


The following functions can be used as a working example of such a script. The setup actions might include connecting to a 
management server or a data source of some kind: 


function Connect-Server {} 


Once the connection is established, a set of objects might be retrieved: 


function Get-ManagementObject { 
1..1@ | ForEach-Object { 
[PSCustomObject J@f{ 
Name = $ 


Property = "Value$_" 


These objects might be modified by another function, which occasionally goes wrong: 


function Set-ManagementObject { 


[CmdletBinding() ] 
param ( 
[Parameter(Mandatory, ValueFromPipeline) ] 
$object, 
$Property 
) 
process { 
try { 


if (Get-Random -Maximum 2) { 
throw 'something went wrong!' 


} 
$Object.Property = $Property 

} catch { 
$PSCmdlet.ThrowTerminatingError($_) 


} 


The following script uses the previous functions. If a terminating error is raised during either the Connect or Get commands, 
the script will stop. If a terminating error is raised when executing the Set command, the script writes a non-terminating error 
and moves onto the next object: 


try { 
Connect-Server 


Get-ManagementObject | ForEach-Object { 


try { 
¢ | Set-ManagementObject -Property 'NewValue' 
} catch { 
Write-Error -ErrorRecord $_ 
} 
} 
} catch { 
throw 


} 


A throw is used in the catch block of the statement above as it does not include a CmdletBinding attribute anda param 
block. 
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Before try, catch, and finally were introduced handling exceptions in PowerShell required the use of a trap statement. 


About trap 
All the way back in PowerShell 1.0, a trap statement was the only way to handle terminating errors in a script. 


As trap very occasionally finds its way into modern scripts, it is beneficial to understand the use of the statement. 


trap is used to catch errors raised anywhere within the scope of the trap declaration, that is, the current scope and any child 
scopes. 


The PowerShell engine finds trap statements anywhere within a script before beginning execution of the script. It deviates 
from the line-by-line approach one might expect when running a PowerShell script. 


Using trap 


A trap statement is declared in a similar manner to the catch block. A trap statement can be created to handle any 
exception type: 


trap { 
Write-Host 'An error occurred' 


A trap statement can also be created to handle a specific exception type: 


trap [ArgumentException] { 
Write-Host ‘Argument exception' 


Ascript may contain more than one trap statement; for example: 


trap [InvalidOperationException] { 
Write-Host ‘An invalid operation’ 


} 
trap { 

Write-Host ‘Catch all other exceptions' 
} 


The ordering of the preceding trap statements does not matter; the statement with the most specific error type is always used 
to handle a given error. 


The following example uses a trap statement at the end of the script to illustrate that the location of the statement is 
unimportant: 


& { 

Write-Host 'Statement1' 

throw 'Statement2' 

Write-Host 'Statement3' 

trap { Write-Host ‘An error occurred’ } 
i 


The error raised by throw causes the trap statement to execute, and then execution stops; Statement3 is never written. 


trap, scope, and continue 
By default, if an error is handled by trap , script execution stops. 


You can use the continue keyword to resume a script at the next statement. 
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The following example handles the error raised by throw and continues onto the next statement: 


& { 
Write-Host 'Statement1' 
throw 'Statement2' 
Write-Host 'Statement3' 
trap { 
Write-Host ‘An error occurred’ 
continue 
} 
} 


The behavior of continue is dependent on the scope the trap statement is written in. In the preceding example, continue 
moves onto writing Statement3 asthe trap statement, and the statements being executed are in the same scope. 


The following script declares a function that throws an error. trap is declared in the parent scope of the function: 


& { 
function Invoke-Something { 
Write-Host 'Statement1' 
throw 'Statement2' 
Write-Host 'Statement3' 


Invoke-Something 
Write-Host 'Done' 


trap { 
Write-Host 'An error occurred' 
continue 


The continue keyword is used, but Statement3 is not displayed. Execution can only continue in the same scope as the trap 
statement. 


Summary 


Error handling in PowerShell is a complex topic, perhaps made more so by inconsistencies in the documentation that can trip up 
new and experienced PowerShell users. 


PowerShell includes the concept of non-terminating errors. Non-terminating errors allow a script, such as one acting ona 
pipeline, to carry on in the event of an error. 


Error handling cannot be said to be consistently implemented in PowerShell. It is not always true that a problem that prevents 
an action from continuing will be described as a terminating error. The reverse is also true: not all actions that allow an action to 
continue are described as non-terminating errors. Great care must therefore be taken when writing code to correctly handle 
error conditions. 


Non-terminating errors should be used when writing commands that expect to act on more than one object if the error is 
restricted to that one object and does not prevent a broader activity from completing. 


You use terminating errors when execution absolutely cannot continue. 


PowerShell includes several different ways to raise both terminating and non-terminating errors. Write-Error , 
$PsCmdlet.WriteError , throw, and $PSCmdlet.ThrowTerminatingError were all introduced in this chapter. 


The problems associated with the use of throw were explored, and there were general recommendations that throw should be 
confined to try and $PSCmdlet.ThrowTerminatingError should be used to end a script in the event of a terminal problem. 


539 
Finally, trap statements were demonstrated. trap came along with PowerShell 1 and is rarely used in modern scripts. trap 


was largely superseded by try, catch, and finally , which were introduced with PowerShell 2. 


The next chapter explores the debugging options available in PowerShell. 
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Debugging and Troubleshooting 


Debugging is the art of discovering, isolating, and fixing bugs in code. The complexity of debugging increases with the 
complexity of the code. 


To a degree, the need to debug complex scripts can be reduced by adopting certain development strategies: 


e Scripts should be broken down into discreet units by using functions 

e Each unit of code should strive to excel at one thing only 

e Each unit of code should strive to be as short as it can reasonably be without sacrificing clarity 
e Tests should be developed to ensure that each unit of code acts as it should 


e Use commands such as Write-Verbose or Write-Debug to write identifiable messages, perhaps including values of 
variables 


Debugging is an inevitable part of the development process. Fortunately, the debugger itself is not difficult to use. 
This chapter explores the following topics: 


e Common problems 
e Debugging in the console 


e Debugging in Visual Studio Code 


Before looking at specific debugging tools, some of the more common problems can be explored. 


Common problems 


When supporting PowerShell development, some problems appear again and again. No one is immune from writing a bug into 
code, no matter how experienced. All experience brings is the ability to find and fix bugs more quickly. 


This section explores the following relatively common problems: 


e Dash characters 
e Operator usage 
e Use of named blocks 


e Problems with variables 


The dash character is a relatively common problem when a piece of code is copied from a blog article or when any code has 
been corrected by a word processor. 


Dash characters 


In PowerShell, a hyphen is used to separate the verb from the noun in command names and is also used to denote a parameter 
name after a command. 


When looking for examples on the internet, it is common to bump into PowerShell code that has been formatted into rich text. 
That is, where the hyphen character has been replaced by a dash character, such as an em or en dash. 


In printed text, this problem is difficult to show, which is why it is a problem in the first place. 


The command may appear ordinary: 
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Get-Process | Where-Object WorkingSet64 -gt 100MB 


If you paste it into the PowerShell console, the dash characters disappear and PowerShell will complain that the command does 
not exist: 


workspace> GetProcess | Where-Object WorkingSet64 gt 100MB 


PS C:\workspace> 


Figure 23.1: Pasting into a console 


If you run the command in either ISE (under PowerShell 5.1) or the Visual Studio integrated terminal, the dash character stays, 
but PowerShell still raises an error about the command name. This error message is even less useful because the dash is still 
present, and the command name appears correct: 


Untitledt psi" X 


1 Get-Process | where-Object WorkingSet64 -gt 100MB 


PS C:\workspace> Get-Process | where-object workingSet64 -gt 100MB 


Figure 23.2: Error when running a selection in ISE 


The same error shows in Visual Studio Code. This time, the code is executed in PowerShell 7.1.3: 


J File Edit Selection View Go Run Terminal Help dash.ps1 - Visual Studio Code - (m| x 


Æ dashpsi X 


C: > workspace > BY dash.ps1 
1 Get-Process | Where-Object WorkingSet64 -gt 100MB 


TERMINAL PROBLEMS OUTPUT DEBUG CONSOLE 1: PowerShell Integrate v +~ D ® ^ x 


ss | Where-Object WorkingSet64 -gt 100MB 
The term 'Get-Process' is not recognized as a name of a 
cmdlet, function, script file, or executable program. 
Check the spelling of the name, or if a path was 
included, verify that the path is correct and try again. 


® Live Share Ln2,Col1 Spaces:4 UTF-8 CRLF PowerShell 


Figure 23.3: Error when running a selection in VS Code 


The syntax highlighter in Visual Studio Code hints at the problem. The Get-Process command in the script has two different 
colors (the actual colors will depend on which themes are enabled). The Get-Process command should have the same 
highlighting as the Where-Object command in this example. 


The color difference is because the dash character used is not a hyphen, it is an en dash, and this confuses PowerShell new and 
old. 


Fixing the dash in the Get-Process command (by retyping the character) fixes the Get-Process command, but despite the 
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filter appearing to be correct, the filter will still fail to apply. 


The same dash appears again in the -gt parameter, and it must also be fixed for the code to work as intended. 


If the problem described previously does not show when pasting the preceding example, the example can be recreated from the 
following string: 


"Get$([char]8211)Process | Where-Object WorkingSet64 $([char]8211)gt 100MB" 


It takes a sharp eye to spot a problem based only on a tiny difference in the length of a dash character. Syntax highlighting 
helps a lot, but this does not clearly point out that there is a problem. 


PSScriptAnalyzer 


The default rules in PSScriptAnalyzer do not warn about this problem, but it is possible to create a rule. My 
module, Indented.ScriptAnalyzerRules , includes a rule for this problem, AvoidDashCharacters : 
https: //github.com/indented-automation/Indented.ScriptAnalyzerRules. 


Operators in PowerShell are another opportunity for bugs to creep into code. 


Operator usage 


Bugs in code can easily be caused by the incorrect usage of an operator. This can be a logical error, such as using -gt , where - 
ge wasa better choice (or vice versa). 


Operators were explored in detail in Chapter 4, Operators. 


Problems can also be caused if = is accidentally used instead of -eq . 


Assignment instead of equality 


Accidentally using the assignment operator, = , in place of the equality operator, -eq , isa common problem. 


When an assignment operation is enclosed in brackets, PowerShell performs the assignment and returns the value that was 
assigned, for example: 


The same applies if the assignment statement is part of an if statement: 


if (¢$variable = $true) { 

Write-Host 'The condition is true’ 
} else { 

Write-Host 'The condition is false' 


} 


In this example, the variable will always have the value $true because of the assignment inside the if statement. 


PowerShell will not highlight this assignment as being an error. It is a legitimate use of the assignment operator. The following 
example captures the output from the Get-Process command at the same time as testing it: 
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$params = @{ 
Name = 'notepad' 
ErrorAction = 'SilentlyContinue' 
} 


if ($process = Get-Process @params) { 

Write-Host "$($process.Name) is running, ID is $($process.ID)" 
} else { 

Write-Host "$($params.name) is not running" 


} 


It would be easy to argue that this is not a great practice. However, there is a difference between what is possible and what 
might be considered a good practice. Since PowerShell will not warn you when this feature is erroneously used, it is important to 
be mindful of attempts to compare values in this manner. 


Comparison operators are not the only type of operator that can occasionally cause confusion. 


-or instead of -and 


The logical operators -and and -or are occasionally easy to confuse. This typically exhibits when converting a thought in a 
natural language directly into code. 


For example, the following statement can be translated into code: 


I want all names which do not start with a or b. 


When writing the code to implement the statement, it is tempting to use the same logical expression as used in natural language; 
in this case, that is "or": 


@( 


' Anna ' 
'Ben' 
uGhipasy 
"David' 
) | Where-Object { $ -notlike 'a*' -or $ -notlike 'b*' } 


Each comparison is evaluated without considering the other. The preceding code will return Anna , because Anna does not start 
with the letter "b", and it will return Ben , because Ben does not begin with the letter "a". 


Using -and in place of -or will fix the problem in the code, as shown here: 


@( 


' Anna ' 
"Ben 
“Ghris® 
"David' 

) | Where-Object { $  -notlike 'a*' -and $ -notlike 'b*' } 


A less common problem can be seen when using a comparison operator on an array. 


Negated array comparisons 
Each of the comparison operators includes a negated version, that is, -eq and -ne, -match and -notmatch , and so on. 
When performing a comparison on an array, it can be tempting to use the negative version of the operator to make an assertion. 


In this example, the -notmatch operator is erroneously used to assert that there are no names in the array that start with" a" 
or" b": 
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garray = @( 
"Anna' 
"Ben' 
Zchruse 
"David' 
) 


if ($array -notmatch '*[ab]') { 
Write-Host "No names starting A or B" 


} 


When acting on an array, the comparison operator does not return a simple $true or $false ; it returns the elements in the 
array that satisfy the comparison. In the preceding example, the result of the comparison is the strings Chris and David. 


If you use the -not operator in conjunction with the -match operator instead, the statement in the body of the if statement 
becomes more accurate: 


garray = @( 
' Anna ' 
'Ben' 
Chris: 
'David' 
) 


if (-not ($array -match '^[ab]')) { 
Write-Host "No names starting A or B" 


} 


It is easy to make a mistake with a comparison operator and, at times, it can be difficult to spot such problems. Testing is an 
important part of any development process. 


PowerShell uses named blocks to support pipeline operations. 


Use of named blocks 


The named blocks begin, process , and end are used to support pipeline operations in PowerShell. Named blocks are also 
used if dynamic parameters are in use. 


Named blocks are explored in Chapter 17, Scripts, Functions, and Script Blocks. 
Dynamic parameters are explored in Chapter 18, Parameters, Validation, and Dynamic Parameters. 


When a named block is used, all code must be placed inside named blocks. 


Code outside of a named block 
Placing code outside of a named block when named blocks are in use can result in several different errors. 


In the following example, a verbose statement has erroneously been placed before the process block. The function uses a brace 
style where the opening brace is placed on the line after the statement: 
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function Get-Something 


i 
[CmdletBinding() ] 
param 
( 
[Parameter (ValueFromPipeline) ] 
[string ]$InputObject 
) 
Write-Verbose ‘Starting Get-Something' 
code 
process 
t 
Write-Verbose "Working on $InputObject" 
i 
} 


It would be easy to expect an editor to regard this script as invalid; however, it is not. When it is run, the following happens: 


1. The Write-Verbose statement will run (showing a message using -Verbose ) 
2. A list of processes will be displayed 


3. The script block containing the second Write-Verbose statement will be emitted, but not executed 


These actions happen because the first statement after param defines the block that is used. Write-Verbose means all content 
is placed in the end block (the default for the function). 


The process statement is considered a command and implicitly aliased to Get-Process . PowerShell attempts to find and run 
a Get- command for all bare words that do not explicitly resolve to another command; for example, running service will 
cause Get-Service to execute. 


If the braces were placed on the same line as the preceding statement, the outcome would be slightly different: 


function Get-Something { 
[CmdletBinding() ] 
param ( 
[Parameter (ValueFromPipeline) ] 
[string ]$InputObject 
) 
Write-Verbose ‘Starting Get-Something' 
process { 
Write-Verbose "Working on $InputObject"™ 


} 


This time, when the function is run, the output is as follows: 


1. The Write-Verbose statement will run (showing a message using -Verbose ) 


2. Get-Process attempts to run, but an error is thrown because the script block containing Write-Verbose is not a valid 
parameter 


The error is: 


Get -Something 
Get-Process: 
Line | 
10 | process { 


| S 


| Cannot evaluate parameter 'Name' because its argument is specified as a script block and there 
is no input. A script block cannot be evaluated without input. 


When one named block is used, all code must be placed inside a named block. Moving the initial Write-Verbose statement 
intoa begin block will fix the problem with the function. 


546 
If no blocks are defined, PowerShell uses the default block. For functions, scripts, and script blocks, the default block is end . For 


functions created using the filter keyword, the default block is process . 


Pipeline without process 


You can create functions with parameters that accept pipeline input. If the body of the function is not placed inside a named 
block, then PowerShell will use the default block, end. 


When you add a pipeline parameter to a function that only implements an end block, the body of the function will only ever 
be able to use the last value in the pipeline: 


function Write-Number { 
[CmdletBinding() ] 
param ( 
[Parameter (ValueFromPipeline) ] 
[int ]$Number 


) 
Write-Host $Number 


When running in a pipeline, only the last of the input values will be displayed: 


1..5 | Write-Number 


Moving the body of the function into a process block will allow it to act on all values from the input pipeline: 


function Write-Number { 
[CmdletBinding() ] 
param ( 
[Parameter (ValueFromPipeline) ] 
[int ]$Number 
) 


process { 
Write-Host $Number 


} 


Perhaps one of the most obvious causes of bugs is a problem with a variable. 


Problems with variables 


Variables are a critical part of almost every script. Potential problems with variables include: 


e Typing errors 
e Incorrectly assigned types 


e Accidental use of reserved variables 


It is difficult to solve the problems above using tools; context plays a large part in determining what is correct. Understanding 
context often requires a human actor. Humans are particularly good at spotting patterns, while computers must be taught 
based on large sample sets. 


One possible technical solution you can use to reduce the risk impact of typing errors is strict mode in PowerShell. 


About strict mode 


Strict mode in PowerShell is used to add several additional parser rules when evaluating scripts. Strict mode is enabled using the 
Set-StrictMode command. The mode is applied to the current scope and all child scopes. 


Set-StrictMode can be used in a module without affecting global scope or any other modules. 
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You can set strict mode to three (effective) values: 
e 1.0 
e 2.0 
e Latest 


For example, the following command sets strict mode to Latest : 


Set-StrictMode -Version Latest 


The effect of each of these modes is described in the help file for Set-StrictMode . When you use Latest as the mode, the 
effect in PowerShell is that it: 


e Prohibits the use of uninitialized variables 
e Prohibits references to non-existent properties of objects 
e Prohibits function calls that use the syntax for calling methods 


e Prohibits out of bounds or unresolvable array indexes 


For example, when enabled in the following function, strict mode causes an error because of the mistake in a variable name: 


function Test-StrictMode { 
Set-StrictMode -Version Latest 
$names = ‘'pwsh', 'powershell' 
foreach ($name in $naems) { 
Write-Host $name 


} 


When the function runs, an error relating to the variable name is displayed: 


Test-StrictMode 
InvalidOperation: 
Line | 


5 | foreach ($name in $naems) { 


| CRIÀ 


| The variable '$naems' cannot be retrieved because it has not been set. 


It is important to note that Set-StrictMode does not enforce scope, so if, for some reason, the $naems variable were to exist in 
a parent scope, the error would not be displayed. 


Set-StrictMode has a mixed reputation in the PowerShell community. On the one hand, it offers some small protection 
against errors. On the other hand, it prohibits certain simple patterns, for instance, testing for a non-existent property on an 
object. 


Without strict mode, it is possible to test for a null, empty, false, or non-existent property inan if statement, as the following 
shows: 


$object = [PSCustomObject]@{ 
ValueA = 1 


} 
if ($object.ValueB) { 


Write-Host "ValueB is set" 


} 


Enabling strict mode will instead show an error: 


Set-StrictMode -Version Latest 
t.ValueB) { 
> Write-Host "V 


> J 
PropertyNotFoundException: The property 'ValueB' cannot be found on this object. Verify that the 
property exists. 


To accommodate strict mode, the condition must become much more complex, making use of the hidden PSObject member of 
objects in PowerShell: 


Set-StrictMode -Version Latest 
$object = [PSCustomObject J@{ 
ValueA = 1 


} 
if ($object.PSObject.Properties.Item('ValueB') -and 


$object.ValueB) { 
Write-Host "ValueB is set" 


Strict mode can be disabled at any time by using the following command: 
Set-StrictMode -Off 


Perhaps most important of all is the fact that the protection strict mode brings is displayed at runtime. As a developer, the 
problem with the variable ideally needs to be shown in an editor when writing code. By the time a script is handed to someone 
else to run, it is far too late to show warnings about variable usage. It is up to each developer to decide whether strict mode 

is appropriate. 


Beyond typing mistakes, one of the most common errors with variables is caused by assigning a type to a variable. 


Variables and types 


Variables in PowerShell may be assigned a type on creation by placing the type on the left-hand side of the variable. For 
example, the variable in the following code is defined as having a string type: 


[string]$string = 'Hello world' 


Any subsequent assignment to the variable will be coerced into a string: 


tring 


System.Collections.Hashtable 


g.GetType() 


The type applies to all assignments made to that variable until either another type is assigned (on the left-hand side of the 
variable) or the variable is destroyed using the Remove-Variable command. 


This is most commonly a problem where a parameter for a command is created with a type, and an attempt is made to reuse the 
variable in the body script or function. 


Assigning a type to a variable can have interesting consequences when applied to an automatic variable. 


Types and reserved variables 


PowerShell includes many built-in variables; these variables are described in the about_automatic_variables help file: 
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Get-Help about_automatic_variables 


Several of these variables only exist in a specific context. For example, the $foreach variable only exists inside a foreach loop. 


If you accidentally use a reserved variable, for instance, as a parameter, and the parameter has an associated type, this can 
break functionality in PowerShell. 


For example, the following switch statement will act on either true or false: 


switch ($true) { 
$true { 'The value is true' } 
$false { 'The value is false' } 


If a type is erroneously assigned to a variable called $switch , the statement will no longer function as the iterator it requires is 
broken. Instead, an error will be displayed: 


[switch]$Switch = $true 

switch ($true) { 
$true { ‘The value is true' } 
$false { 'The value is false’ } 


The following System.SZArrayEnumerator error is the type the $switch variable should have but no longer does because of 
the previous assignment statement: 


MetadataError: Cannot convert value "System.SZArrayEnumerator" to type 


"System.Management .Automation.SwitchParameter". Boolean parameters accept only Boolean values and 
numbers, such as $True, $False, 1 or ð. 


PowerShell will not prevent this from happening; it is up to a developer to avoid this problem in the first place. 


The problem with switch in the preceding example will persist until either PowerShell is restarted or the variable is removed: 
Remove-Variable switch 


It is important to be mindful of and avoid using automatic variables in code. 


Being aware of potential problems avoids the need for extensive debugging. When the problem is less obvious, the debugger can 
be used. 


Debugging in the console 


The PowerShell debugger allows code execution to be paused and the state of a script to be analyzed at a specific point. 
These points are known as breakpoints and are set using the Set-PSBreakpoint command. 


PowerShell describes the following operations in the about_Debuggers help file: 
Get-Help about_Debuggers 


You can use the Set-PSBreakpoint command to set a breakpoint when a command is run, when a variable is used, or on a 
specific line in a saved script. 


Setting a command breakpoint 
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Setting a breakpoint on a command will trigger the debugger when that command is run. 


In the next example, a breakpoint is created that triggers when the Get-Process command runs. As Get-Process is inside a 
loop, it will be possible to inspect the state of variables inside the loop in the debugger: 


Set- ih ag eee -Command Get-Process 
$names = 5 
foreach ($name in branes) { 
Get-Process $name -ErrorAction SilentlyContinue 


} 


When the example is run, the DBG prompt will appear: 


Hit Command breakpoint on 'Get-Process' 
At line:2 char:5 


+ Get-Process $name -ErrorAction SilentlyContinue 


[DBG]: PS C:\workspace>> 


Pressing ? at the DBG prompt will show the possible debug actions. The output is shown in Figure 23.4: 
PS C:\workspace> foreach ($name in $names 

>> Get-Process $name -ErrorAction SilentlyContinue 

phen debug mode. Use h or ? for help. 

Hit Command breakpoint on ‘Get-Process' 


At line:2 char:5 : À ; 
+ Get-Process $name -ErrorAction Silent lyContinue 


+ 
[DBG]: PS C:\workspace>> ? 
stepInto Single step (step into functions, scripts, etc.)_ 
stepOver Step to next statement (step over functions, scripts, etc.) 
stepOut Step out of the current function, script, etc. 
continue Continue operation _ 
uit Stop operation and exit the debugger 
etach Continue operation and detach the debugger. 
Get-PSCallStack Display call stack 
List source code for the current script. R 
Use "list" to start from the current line, “list <m>" 
to start from line <m>, and "list <m> <n>" to list <n> 
lines starting from line <m> 
<enter> Repeat last command if it was stepInto, stepOver or list 


Zoh displays this help message. 


For instructions about how to customize your debugger prompt, type “help about_prompt" 


Figure 23.4: Error when running a selection in VS Code 


In addition to these actions, any variable values may be inspected at this point in the loop simply by typing the variable name 
into the prompt: 


[DBG]: PS C:\workspace>> $name 


powershell 


The current script may be displayed using the list command inside the debug prompt. By default, it will list the entire script. 
Arange of lines may be displayed by specifying optional start and end line numbers for the list command: 


[DBG]: PS C:\workspace>> list 1 2 


1: foreach ($name in $names) { 
Dik Get-Process $name -ErrorAction SilentlyContinue 


If the end line is not specified, the command will display all script lines from the start to the end of the script. 


Pressing c , to continue, will move to the next iteration in the loop. If any of the processes are not running, an error will be 
displayed by Get-Process . This time, the $name variable will show the second item in the loop. 


[DBG]: PS C:\workspace>> $name 


pwsh 


If the process is running, the process objects will be returned. Once the script completes, the debug prompt will close. 


Breakpoints in a session can be viewed using the Get-PSBreakpoint command, and any existing breakpoint can be removed 
using Remove-PSBreakpoint . The following command removes all breakpoints in the session: 


Get-PSBreakpoint | Remove-PSBreakpoint 


Confusing breakpoints 


Breakpoints should be removed after running any examples to avoid confusing results. 


Breakpoints may also be set on variables. 


Using variable breakpoints 


When a breakpoint is set on a variable, it will, by default, only trigger when the variable is set (written to). 


Writing to a variable means changing the value held by the variable. In the following example, the value of the $newValue 
variable is set five times, once per iteration of the loop: 


foreach ($value in 1..5) { 
$new/alue = $value 


} 
Setting a breakpoint based on this variable will therefore cause the debugger to pause execution five times: 


Set-PSBreakpoint -Variable newValue 
foreach ($value in 1..5) { 
$newValue = $value 


} 


If a variable holds a collection, such as a Hashtable, it is important to note that adding a key is not a write operation with respect 
to the variable. In this example, the debugger will only trigger when $values is created: 


Set-PSBreakpoint -Variable values 


$values = @{} 
foreach ($value in 1..5) { 
$values[$value] = $value 


} 


The operation to add a key to the Hashtable is performed on the value of the variable, which is read from the variable object. 


The -Mode parameter, which has the default value Write , may be used to trigger the debugger when a variable is read by 
setting the argument to either Read or ReadWrite . 
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If the last breakpoint is removed, and a new breakpoint added, the debugger will trigger five times again: 


Set-PSBreakpoint -Variable values -Mode Read 
$values = @{} 
foreach ($value in 1..5) { 

$values[$value] = $value 


} 


The most common use of the debugger is a line breakpoint. 


Setting a line breakpoint 


A line breakpoint can only be set if a script is saved to a file. The debugger will trigger when the line in the script is executed. The 
debugger may be used to explore the current state: 


@' 
$names = 'powershell', 'pwsh', ‘code' 
foreach ($name in $names) { 

Get-Process $name -ErrorAction SilentlyContinue 


Ji 

'@ | Set-Content script.ps1 
Set-PSBreakpoint -Script script.ps1 -Line 3 
.\script.ps1 


When accessing script variables inside the debugger, several automatic variables cannot be viewed: 


e $Args 
e $¢Input 
e ¢MyInvocation 


e $PSBoundParameters 
These variables are used by the debugger and are therefore overwritten by the debugger, hiding any values the script might use. 


The value of an automatic variable should be assigned to another named variable in the script to view the content of that 
variable. For example, the $PSBoundParameters variable value is assigned to another variable in the following example: 


@' 
param ( 

[string[]]$Name 
) 


$boundParameters = $PSBoundParameters 
foreach ($processName in $Name) { 
Get-Process $name -ErrorAction SilentlyContinue 
} 
'@ | Set-Content script.ps1 
Set-PSBreakpoint -Script script.psi -Line 7 


When the debugger starts, you can inspect the value of the $boundParameters variable, but the value of 
$PSBoundParameters is not available. This is shown in the following snippet: 


PS C:\workspace> .\script.ps1 -Name 'pwsh' 

Hit Line breakpoint on 'C:\workspace\script.ps1:7' 
At C:\workspace\script.ps1:7 char:5 

+ Get-Process $name 

+ RAR 

[DBG]: PS C:\workspace>> $PSBoundParameters 

[DBG]: PS C:\workspace>> $boundParameters 

Key Value 


Name {pwsh} 


Setting breakpoints using line numbers in the console is possible, but is not the easiest way to work with the debugger. 


The Visual Studio Code editor includes a debugger interface, which is a lot easier to work with than the command line. 


Debugging in Visual Studio Code 


Visual Studio Code and other interactive editors greatly simplify working with the debugger. The debugger is accessed via a 
button on the left-hand side of the editor. 


Using the debugger 


The debugging options in Visual Studio Code, by default, will run a script and stop at any defined breakpoint. 


The param block is removed from script.ps1 for this example, making the content: 


$names = ‘powershell', 'pwsh', ‘code' 
foreach ($name in $names) { 
Get-Process $name -ErrorAction SilentlyContinue 


} 


You can add breakpoints to a script by clicking to the left of the line number. A breakpoint has been added to script.ps1, as 
shown in Figure 23.5: 


xX) File Edit Selection View Go Run Terminal Help script.ps1 - workspace - Visual Studio Code = o X 
RUN AND DEBUG Le E scriptps1 X > > R D 
V RUN As 
1 $names = 'powershell', ‘pwsh', ‘code’ 5 
Run and Debug 2 foreach ($name in $names) © 
e@ 3 Get-Process $name -ErrorAction SilentlyContinue 
4 } ry 


> To customize Run and Debug 
be 


create a launchjson file 


Show all automatic debug 
configurations. 


Y BREAKPOINTS 
è M script.ps1 


X ®O0AO0 F Live Share Ln5,Col1 Spaces:4 UTF-8 LF PowerShell 


Figure 23.5: Debugging in Visual Studio Code 


The breakpoint appears as a red dot next to the line. When the Run and Debug button is pressed, Visual Studio Code will 
execute the script. The script in this case is run in PowerShell 7.1 based on the version in the bottom-left corner of the editor. 
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When run, the VARIABLES and CALL STACK boxes will fill as shown in Figure 23.6: 


RU.. D NoConfiguratvy & - As EID OY TOD 
VARIABLES BI script ps1 > 
V Auto 1 $names = ‘powershell', ‘pwsh', ‘code’ 
$^: "A" 2 foreach ($name in $names) < 
$$: "}" © 3 D Get-Process $name -ErrorAction Sil 
4 } 


$ConfirmPreference: High 
$DebugPreference: Silentlyc.. 

> $Error: [ArrayList: 0] 
$ErrorActionPreference: Con... 
$ErrorView: ConciseView 

> $foreach: [SZArrayEnumerato... 
$FormatEnumerationLimit: 4 
$InformationPreference: Sil.. 
$LASTEXITCODE: 128 


> WATCH 


W CALL STACK PAUSED ON BREAKPOINT 


<ScriptBlock> script.ps1 (3:5 


Figure 23.6: Accessible variables in the debugger 


The icons in the bar at the top of the window present the different options for the debugger: 


Run Terminal Help script.ps1 - workspace - 


LE Ee m sa g D ff 


EF script.ps1 >. 


Figure 23.7: Debugger controls 
Pressing the left-most icon, Continue, will move on to the next breakpoint. 


The VARIABLES box on the left-hand side shows the state of each of the variables in PowerShell at the point the debugger 
stopped. The values of the $name and $names_ variables are visible and can be inspected. 


Viewing the CALL STACK 


The CALL STACK is used to record the path taken to a specific point in code. The CALL STACK includes a record of each 
command, script, or script block that was called. 


Ascript that contains a single command with a breakpoint, such as the following script, will only contain itself in the CALL 
STACK: 


Write-Host ‘Hello world' 


This is shown in Figure 23.8: 
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R.. |D PowerShell: Lev & = &¥scriptps) FIP OY TOD 
> VARIABLES Æ script.ps1 
> WATCH (> 1  Write-Host ‘Hello world' 


V CALL STACK PAUSED ON BREAKPOINT () 


<ScriptBlock>  script.ps1 1:1 


Figure 23.8: Viewing the CALL STACK 


Each script, function, or script block that is called to get to the breakpoint is added to the CALL STACK. In the following script, 
getting to the breakpoint means calling the first function, then the second, and then the third: 


function first { 


second 

} 

function second { 
third 

i; 


function third { 
Write-Host ‘Hello world' 


} 


first 


Each time a function is called from inside an existing function (or script, or script block), a new value is added to the CALL 
STACK: 


R.. [D> PowerShel: Lev & = Æ scriptps) #2 ID OY TOD 
> VARIABLES BY script.ps1 > Ọ third () 
> WATCH 1 refer 
\” CALL STACK PAUSED ON BREAKPOINT 1 v function first { 
A s 2 n 

third script.ps1 18:5 a } eae 

second script.ps1 (5 iata: 

first script.ps1 (2 4 v function second { 

<ScriptBlock> script.ps1 10 5 third 

6 } 


1 reference 


7 function third { 


© 8  OwWrite-Host. 'Hello world’ 
9 } 
10 first 


Figure 23.9: Viewing the CALL STACK with nested functions 


Clicking on each of the entries in the CALL STACK will show what was called to get to the breakpoint. The final entry in the 
CALL STACK will highlight line 10. 


This allows a developer to follow the path to the breakpoint even if a script is more complex. 


The functions in the previous example do not make use of any variables. The Auto section of the VARIABLES window is 
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therefore empty. 


Using launch configurations 


A launch configuration is a JSON file that describes how debugging should be performed. Launch configurations are valuable if 


a script requires arguments. Without a launch configuration, you would have to edit a script so that it wouldn't require 
arguments. 


Launch configurations are only available when Visual Studio Code has a directory open. If the editor was used to open a file 
path, the Run and Debug option will show the need to open a folder: 


RUN AND DEBUG: RUN ‘++ BY scriptps1 X 


C: > workspace > BY script.ps1 > [8] $names 
Run and Debug 1 $names = 'powershell', ‘pws 


foreach ($name in $names) { 


2 
To customize Run and Debug, open 3 gut-Process Sram <Ero 
4 


a folder and create a launch.json 
file. 


ty 


Show all automatic debug 
configurations. 


Figure 23.10: Opening a folder dialog 


Selecting open a folder will offer a prompt for the directory containing the current script. Clicking OK will open that directory, 
and the Explorer option will contain all the files in that folder. 


Returning to the Run and Debug option will now offer an option to create a launch configuration JSON file: 


RUN AND DEBUG e BF script.ps 
V RUN BF script.ps 
a 


Run and Debug 


2 

@® 3 

To customize Run and Debug Pi 
create a launch,json file. 


Show all automatic debug 
configurations. 


Figure 23.11: Creating a launch configuration 


Clicking on the new option will open a new menu. Selecting Launch Current File will create a launch.json file ina 
.vscode folder in the current directory. 


The launch.json file can be edited, adding a configuration that can be used to run a specific script. 


Each configuration is written in JSON. In the following example, the existing entry is copied and used to create a new launch 
configuration. The configuration includes the "args" property, and a value is set to satisfy the script: 
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{ 
"version": "0.2.0", 
"configurations": [ 
{ 
"name": "PowerShell: Launch Current File", 
"type": "PowerShell", 
"request": "launch", 
Uscmiptys =$ifilert, 
"cwd": "${file}" 
}s 
{ 
"name": "PowerShell: Launch with arguments", 
"type": "PowerShell", 
"request": "launch", 
"Script™: “S${file}; 
"cwd": "${file}", 
zares: ii 
"-Name pwsh" 
] 
J 
] 
} 


Ascript requiring arguments can now be run in the debugger by choosing the new PowerShell: Launch with arguments 
configuration: 


<j File Edit Selection View Go Run Terminal Help script.ps1 - workspace - Visual Studio Code = o x 


RUN AND DEBUG D| PowerShell: Launch Current File ~| & = Æ scriptps11 X DPRD- 


PowerShell; Laun rent F 
ARARE owerShell: Launch Current File a 
PowerShell: Launch with arguments 
param ( 
Node.js [string |]$Name 


Add Configuration. ) 


foreach $processName in $Name) © 


1 

2 

3 

4 

5  $boundParameters = $PSBoundParameters 

6 

7 Get-Process $name -ErrorAction SilentlyContinue 
8 


> WATCH 
V CALL STACK 


X @OA1 F LiveShare Ln9,Col1 Spaces:4 UTF-8 LF PowerShell 
- o 


Figure 23.12: Launch with arguments 
A complex script may include many variables, which can make attempting to track values using the VARIABLES window 
difficult. 


Using WATCH 


You can use the WATCH window to track a smaller number of variables or expressions as breakpoints are triggered. 


The next example script sets two variables with every iteration of a loop: 


$AValue = $ZValue = @ 

for ($i = ð; $i -lt 10; $i++) { 
$AValue = $i 
$ZValue = $i * 2 


The names of the variables mean they will appear at opposite ends of the VARIABLES window. 


Each variable can be added to the WATCH window and the debugger will show the current value of those variables. Before the 
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debugger runs, the value is shown as not available: 


V WATCH + a ð 


$AValue: not available 
'$ZValue | 


Figure 23.13: WATCH expressions 


Once the debugger is started, the variables will be given their initial values as defined by the script. Then, each time Continue is 
pressed, the values will update to reflect that iteration of the loop. 


For example, after the fifth press of Continue, the updated state of the variables is as follows: 


xX] Eile Edit Selection View Go Run * script.ps1 - workspace - Visual Stu... — o x 
R.. D PowerShell: lev  - HID OY TOO >rPpRO- 
V VARIABLES BF script.ps1 > 
V Auto 1 $AValue = $ZValue = @ ee 
$^: "@{" 2 for ($i = 6; $i -lt 10; $i++) { 
$$: "}" 3 $AValue = $i m 
; 4 ZValue = $i *-2 
$AValue: 5 © 5 | D$ $ 
$ConfirmPreference: High 
N ENahurNnalananans Clant Ir 
SEIE v WATCH 
$AValue: 5 
$ZValue: 8 


> CALL STACK 
Y BREAKPOINTS 
è Mscript.pst 4 


X @OA2 Æ PowerShell: Launch Current File (workspace) @ Live Share LF PowerShell 


Figure 23.14: WATCH in action 


The expression added to WATCH can be any command or statement that returns a simple value. Complex values, such as 
custom objects, will not display well in the WATCH window. 


The debugging in Visual Studio Code is an especially useful tool that simplifies debugging complex scripts. 


Summary 


Some errors in PowerShell come up again and again, and being able to spot and identify such errors can reduce the amount of 
time spent attempting to isolate a problem. Several common problems were introduced based on real-world bugs. 


Not every bug can be attributed to a common error, and sometimes a more extensive investigation is required. PowerShell 
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includes a debugger that you can use from either the command line or an editor to isolate bugs. 


Visual Studio is a PowerShell editor that simplifies using the PowerShell debugger. It makes it easier for a developer to use line- 
based debugging. 


This chapter brings this book to a close. PowerShell is full of rabbit holes to dive down and explore, more than is possible to 
include in this book. 


Perhaps one of the most prominent features of PowerShell is consistency. Each command, each module, is presented 
consistently, and each has help immediately available. 


The move to .NET Core and open source has opened interesting avenues for exploring the inner workings of PowerShell, fixing 
bugs, and extending the language. 


PowerShell is supported by a fantastic friendly community, willing to help and chat regardless of experience level. User groups 
exist in many parts of the world, and the virtual PowerShell user group is always available: https : //poshcode.org/ 


All these things combine to make PowerShell a fun language to learn and use. 


